聊天 Chat


OpenAI 对话格式 （Chat Completions）

官方文档

📝 简介

给定一组包含对话的消息列表，模型将返回一个响应。相关指南可参阅OpenAI官网：Chat Completions

💡 请求示例

基础文本对话 ✅

curl https://$Burncloud_API_BaseUrl/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $Burncloud_API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {
        "role": "developer",
        "content": "你是一个有帮助的助手。"
      },
      {
        "role": "user",
        "content": "你好！"
      }
    ]
  }'

响应示例:

{
  "id": "chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT",
  "object": "chat.completion",
  "created": 1741569952,
  "model": "gpt-4.1-2025-04-14",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！我能为你提供什么帮助？",
        "refusal": null,
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 19,
    "completion_tokens": 10,
    "total_tokens": 29,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "service_tier": "default"
}

图像分析对话 ✅

curl https://$Burncloud_API_BaseUrl/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $Burncloud_API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "这张图片里有什么？"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
            }
          }
        ]
      }
    ],
    "max_tokens": 300
  }'

响应示例:

{
  "id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG",
  "object": "chat.completion",
  "created": 1741570283,
  "model": "gpt-4.1-2025-04-14",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "图片展示了一条穿过茂密绿色草地或草甸的木制栈道。天空湛蓝，点缀着几朵散落的云彩，给整个场景营造出宁静祥和的氛围。背景中可以看到树木和灌木丛。",
        "refusal": null,
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1117,
    "completion_tokens": 46,
    "total_tokens": 1163,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "service_tier": "default",
  "system_fingerprint": "fp_fc9f1d7035"
}

流式响应 ✅

curl https://$Burncloud_API_BaseUrl/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $Burncloud_API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {
        "role": "developer",
        "content": "你是一个有帮助的助手。"
      },
      {
        "role": "user",
        "content": "你好！"
      }
    ],
    "stream": true
  }'

流式响应示例:

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]}

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"content":"你好"},"logprobs":null,"finish_reason":null}]}

// ... 更多数据块 ...

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}]}

函数调用 ✅

curl https://$Burncloud_API_BaseUrl/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $Burncloud_API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {
        "role": "user",
        "content": "波士顿今天的天气怎么样？"
      }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_current_weather",
          "description": "获取指定位置的当前天气",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "城市和州，例如 San Francisco, CA"
              },
              "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"]
              }
            },
            "required": ["location"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

响应示例:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1699896916,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_current_weather",
              "arguments": "{\n\"location\": \"Boston, MA\"\n}"
            }
          }
        ]
      },
      "logprobs": null,
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 82,
    "completion_tokens": 17,
    "total_tokens": 99,
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  }
}

Logprobs 请求 ✅

curl https://$Burncloud_API_BaseUrl/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $Burncloud_API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {
        "role": "user",
        "content": "你好！"
      }
    ],
    "logprobs": true,
    "top_logprobs": 2
  }'

响应示例:

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1702685778,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！我能为你提供什么帮助？"
      },
      "logprobs": {
        "content": [
          {
            "token": "Hello",
            "logprob": -0.31725305,
            "bytes": [72, 101, 108, 108, 111],
            "top_logprobs": [
              {
                "token": "Hello",
                "logprob": -0.31725305,
                "bytes": [72, 101, 108, 108, 111]
              },
              {
                "token": "Hi",
                "logprob": -1.3190403,
                "bytes": [72, 105]
              }
            ]
          },
          {
            "token": "!",
            "logprob": -0.02380986,
            "bytes": [
              33
            ],
            "top_logprobs": [
              {
                "token": "!",
                "logprob": -0.02380986,
                "bytes": [33]
              },
              {
                "token": " there",
                "logprob": -3.787621,
                "bytes": [32, 116, 104, 101, 114, 101]
              }
            ]
          },
          {
            "token": " How",
            "logprob": -0.000054669687,
            "bytes": [32, 72, 111, 119],
            "top_logprobs": [
              {
                "token": " How",
                "logprob": -0.000054669687,
                "bytes": [32, 72, 111, 119]
              },
              {
                "token": "<|end|>",
                "logprob": -10.953937,
                "bytes": null
              }
            ]
          },
          {
            "token": " can",
            "logprob": -0.015801601,
            "bytes": [32, 99, 97, 110],
            "top_logprobs": [
              {
                "token": " can",
                "logprob": -0.015801601,
                "bytes": [32, 99, 97, 110]
              },
              {
                "token": " may",
                "logprob": -4.161023,
                "bytes": [32, 109, 97, 121]
              }
            ]
          },
          {
            "token": " I",
            "logprob": -3.7697225e-6,
            "bytes": [
              32,
              73
            ],
            "top_logprobs": [
              {
                "token": " I",
                "logprob": -3.7697225e-6,
                "bytes": [32, 73]
              },
              {
                "token": " assist",
                "logprob": -13.596657,
                "bytes": [32, 97, 115, 115, 105, 115, 116]
              }
            ]
          },
          {
            "token": " assist",
            "logprob": -0.04571125,
            "bytes": [32, 97, 115, 115, 105, 115, 116],
            "top_logprobs": [
              {
                "token": " assist",
                "logprob": -0.04571125,
                "bytes": [32, 97, 115, 115, 105, 115, 116]
              },
              {
                "token": " help",
                "logprob": -3.1089056,
                "bytes": [32, 104, 101, 108, 112]
              }
            ]
          },
          {
            "token": " you",
            "logprob": -5.4385737e-6,
            "bytes": [32, 121, 111, 117],
            "top_logprobs": [
              {
                "token": " you",
                "logprob": -5.4385737e-6,
                "bytes": [32, 121, 111, 117]
              },
              {
                "token": " today",
                "logprob": -12.807695,
                "bytes": [32, 116, 111, 100, 97, 121]
              }
            ]
          },
          {
            "token": " today",
            "logprob": -0.0040071653,
            "bytes": [32, 116, 111, 100, 97, 121],
            "top_logprobs": [
              {
                "token": " today",
                "logprob": -0.0040071653,
                "bytes": [32, 116, 111, 100, 97, 121]
              },
              {
                "token": "?",
                "logprob": -5.5247097,
                "bytes": [63]
              }
            ]
          },
          {
            "token": "?",
            "logprob": -0.0008108172,
            "bytes": [63],
            "top_logprobs": [
              {
                "token": "?",
                "logprob": -0.0008108172,
                "bytes": [63]
              },
              {
                "token": "?\n",
                "logprob": -7.184561,
                "bytes": [63, 10]
              }
            ]
          }
        ]
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 9,
    "total_tokens": 18,
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "system_fingerprint": null
}

📮 请求

端点

POST /v1/chat/completions

创建给定聊天对话的模型响应。更多详情请参阅文本生成、视觉和音频指南。

鉴权方法

在请求头中包含以下内容进行 API 密钥认证：

Authorization: Bearer $Burncloud_API_KEY

其中 $Burncloud_API_KEY 是您的 API 密钥。您可以在 OpenAI 平台的 API 密钥页面中找到或生成 API 密钥。

请求体参数

messages

到目前为止包含对话的消息列表。根据使用的模型，支持不同的消息类型（形式），如文本、图像和音频。

消息类型 描述
Developer message 开发者提供的指令，模型应遵循这些指令，无论用户发送什么消息。在 o1 模型及更新版本中，开发者消息取代了之前的系统消息。
System message 开发者提供的指令，模型应遵循这些指令，无论用户发送什么消息。在 o1 模型及更新版本中，请使用开发者消息代替。
User message 由终端用户发送的消息，包含提示或额外的上下文信息。
Assistant message 模型响应用户消息发送的消息。
Tool message 工具消息的内容。
Function message 已弃用。

Developer message 属性：

属性 类型 必需 描述
role 字符串 是 消息作者的角色，此处为 developer。
content 字符串或数组 是 开发者消息的内容。可以是文本内容（字符串）或内容部分数组。
name 字符串 否 参与者的可选名称。为模型提供信息以区分相同角色的参与者。

System message 属性：

属性 类型 必需 描述
role 字符串 是 消息作者的角色，此处为 system。
content 字符串或数组 是 系统消息的内容。可以是文本内容（字符串）或内容部分数组。
name 字符串 否 参与者的可选名称。为模型提供信息以区分相同角色的参与者。

User message 属性：

属性 类型 必需 描述
role 字符串 是 消息作者的角色，此处为 user。
content 字符串或数组 是 用户消息的内容。可以是文本内容（字符串）或内容部分数组。
name 字符串 否 参与者的可选名称。为模型提供信息以区分相同角色的参与者。

内容部分类型：

内容部分类型 描述 可用于
文本内容部分 文本输入。 所有消息类型
图像内容部分 图像输入。 用户消息
音频内容部分 音频输入。 用户消息
文件内容部分 文件输入，用于文本生成。 用户消息
拒绝内容部分 模型生成的拒绝消息。 助手消息

文本内容部分属性：

属性 类型 必需 描述
text 字符串 是 文本内容。
type 字符串 是 内容部分的类型。

图像内容部分属性：

属性 类型 必需 描述
image_url 对象 是 包含图像URL或base64编码的图像数据。
type 字符串 是 内容部分的类型。

图像URL对象属性：

属性 类型 必需 描述
url 字符串 是 图像的URL或base64编码的图像数据。
detail 字符串 否 指定图像的详细级别。默认为 auto。

音频内容部分属性：

属性 类型 必需 描述
input_audio 对象 是 包含音频数据的对象。
type 字符串 是 内容部分的类型。始终为 input_audio。

音频输入对象属性：

属性 类型 必需 描述
data 字符串 是 base64编码的音频数据。
format 字符串 是 编码音频数据的格式。当前支持 "wav" 和 "mp3"。

文件内容部分属性：

属性 类型 必需 描述
file 对象 是 包含文件数据的对象。
type 字符串 是 内容部分的类型。始终为 file。

文件对象属性：

属性 类型 必需 描述
file_data 字符串 否 base64编码的文件数据，用于将文件作为字符串传递给模型。
file_id 字符串 否 已上传文件的ID，用作输入。
filename 字符串 否 文件名，用于将文件作为字符串传递给模型。

Assistant message 属性：

属性 类型 必需 描述
role 字符串 是 消息作者的角色，此处为 assistant。
content 字符串或数组 否 助手消息的内容。除非指定了 tool_calls 或 function_call，否则为必需。
name 字符串 否 参与者的可选名称。为模型提供信息以区分相同角色的参与者。
audio 对象或null 否 关于模型先前音频响应的数据。
function_call 对象或null 否 已弃用，由 tool_calls 替代。应调用的函数的名称和参数，由模型生成。
tool_calls 数组 否 模型生成的工具调用，如函数调用。
refusal 字符串或null 否 助手的拒绝消息。

Tool message 属性：

属性 类型 必需 描述
role 字符串 是 消息作者的角色，此处为 tool。
content 字符串或数组 是 工具消息的内容。
tool_call_id 字符串 是 此消息响应的工具调用。

Function message 属性：（已弃用）

属性 类型 必需 描述
role 字符串 是 消息作者的角色，此处为 function。
content 字符串或null 是 函数消息的内容。
name 字符串 是 要调用的函数的名称。

model

要使用的模型 ID。有关哪些模型适用于 Chat API 的详细信息，请参阅模型端点兼容性表。

store

是否存储此聊天补全请求的输出以用于我们的模型蒸馏或评估产品。

reasoning_effort

约束推理模型的推理工作。当前支持的值为 low、medium 和 high。减少推理工作可以加快响应速度并减少响应中用于推理的标记数。

metadata

可以附加到对象的16个键值对集合。这对于以结构化格式存储对象的其他信息很有用,并可以通过 API 或仪表板查询对象。

键是最大长度为64个字符的字符串。值是最大长度为512个字符的字符串。

modalities

您希望模型为此请求生成的输出类型。大多数模型都能生成文本,这是默认设置: ["text"]

该模型还可以用于生成音频。要请求此模型同时生成文本和音频响应,您可以使用: ["text", "audio"]

prediction

预测输出的配置,当提前知道模型响应的大部分内容时,可以大大提高响应时间。这在您只对文件进行微小更改时最常见。

可能的类型：

类型 描述
静态内容 静态预测输出内容，例如正在重新生成的具有微小更改的文本文件内容。

静态内容属性：

属性 类型 必需 描述
content 字符串或数组 是 生成模型响应时应匹配的内容。如果生成的标记与此内容匹配，则整个模型响应可以更快地返回。
type 字符串 是 要提供的预测内容类型。当前类型始终为 content。

内容可能的类型：

  1. 文本内容（字符串） - 用于预测输出的内容。这通常是您正在重新生成的文件的文本，只有微小更改。

  2. 内容部分数组（数组） - 具有定义类型的内容部分数组。支持的选项因用于生成响应的模型而异。可以包含文本输入。

内容部分数组属性：

属性 类型 必需 描述
text 字符串 是 文本内容。
type 字符串 是 内容部分的类型。

audio

音频输出的参数。当使用 modalities: ["audio"] 请求音频输出时需要。

属性 类型 必需 描述
format 字符串 是 指定输出音频格式。必须是以下之一：wav、mp3、flac、opus 或 pcm16。
voice 字符串 是 模型用于响应的声音。支持的声音包括：alloy、ash、ballad、coral、echo、fable、nova、onyx、sage 和 shimmer。

temperature

要使用的采样温度，介于 0 和 2 之间。较高的值（如0.8）会使输出更加随机，而较低的值（如0.2）会使其更加集中和确定性。我们通常建议更改此值或 top_p，但不要同时更改。

top_p

一种替代采样温度的方法，称为核采样，其中模型考虑具有 top_p 概率质量的标记结果。因此，0.1 意味着只考虑包含前 10% 概率质量的标记。

我们通常建议更改此值或 temperature，但不要同时更改。

n

为每个输入消息生成多少个聊天补全选择。请注意，您将根据所有选择生成的标记数量收费。保持 n 为 1 可最大限度地降低成本。

stop

API 将停止生成更多标记的最多 4 个序列。返回的文本不会包含停止序列。

max_tokens

聊天补全中可以生成的最大标记数。此值可用于控制通过 API 生成的文本成本。

该值现已弃用，取而代之的是 max_completion_tokens，并且与 o1 系列模型不兼容。

max_completion_tokens

补全中可以生成的标记数的上限，包括可见输出标记和推理标记。

presence_penalty

介于 -2.0 和 2.0 之间的数字。正值根据新标记到目前为止在文本中出现的情况来惩罚它们，从而增加模型讨论新主题的可能性。

frequency_penalty

介于 -2.0 和 2.0 之间的数字。正值根据新标记到目前为止在文本中的现有频率来惩罚它们，从而降低模型逐字重复同一行的可能性。

logit_bias

修改指定标记出现在补全中的可能性。

接受一个 JSON 对象，该对象将标记（由分词器中的标记 ID 指定）映射到从 -100 到 100 的关联偏差值。在数学上，偏差被添加到模型在采样之前生成的对数中。确切的效果会因模型而异，但介于 -1 和 1 之间的值应该会减少或增加选择的可能性；像 -100 或 100 这样的值应该导致相关标记被禁止或独占选择。

logprobs

是否返回输出标记的对数概率。如果为 true，则返回 message.content 中每个输出标记的对数概率。

user

表示最终用户的唯一标识符，可以帮助 OpenAI 监控和检测滥用行为。了解更多。

service_tier

指定用于处理请求的延迟层级。此参数与订阅了 scale tier 服务的客户相关：

stream_options

流式响应的选项。仅在设置 stream: true 时使用。

可能的属性：

属性 类型 必需 描述
include_usage 布尔值 否 如果设置，将在 data: [DONE] 消息之前流式传输一个附加块。该块上的 usage 字段显示整个请求的令牌使用统计信息，choices 字段始终为空数组。所有其他块也将包含 usage 字段，但值为 null。注意：如果流被中断，您可能不会收到包含请求总令牌使用量的最终使用块。

response_format

指定模型必须输出的格式。

重要提示：使用 JSON 模式时，您还必须通过系统或用户消息自行指示模型生成 JSON。否则，模型可能会生成无尽的空白直到生成达到令牌限制。

可能的类型：

类型 描述
text 默认响应格式。用于生成文本响应。
json_schema JSON Schema 响应格式。用于生成结构化 JSON 响应。了解更多关于结构化输出的信息。
json_object JSON 对象响应格式。一种较老的生成 JSON 响应的方法。对于支持的模型，推荐使用 json_schema。

text 属性：

属性 类型 必需 描述
type 字符串 是 正在定义的响应格式类型。始终为 text。

json_schema 属性：

属性 类型 必需 描述
json_schema 对象 是 结构化输出配置选项，包括 JSON Schema。
type 字符串 是 正在定义的响应格式类型。始终为 json_schema。

json_schema.json_schema 属性：

属性 类型 必需 描述
name 字符串 是 响应格式的名称。必须是 a-z、A-Z、0-9 或包含下划线和破折号，最大长度为 64。
description 字符串 否 响应格式的用途描述，模型用它来确定如何以该格式响应。
schema 对象 否 响应格式的架构，描述为 JSON Schema 对象。
strict 布尔值或 null 否 是否在生成输出时启用严格架构遵守。如果设置为 true，模型将始终遵循 schema 字段中定义的确切架构。strict 为 true 时，仅支持 JSON Schema 的子集。

json_object 属性：

属性 类型 必需 描述
type 字符串 是 正在定义的响应格式类型。始终为 json_object。

seed

tools

模型可能调用的工具列表。目前仅支持函数作为工具。使用此参数提供模型可能生成 JSON 输入的函数列表。最多支持 128 个函数。

属性：

属性 类型 必需 描述
function 对象 是 要调用的函数信息
type 字符串 是 工具的类型。目前，仅支持 function。

function 属性：

属性 类型 必需 描述
name 字符串 是 要调用的函数名称。必须是a-z、A-Z、0-9，或包含下划线和破折号，最大长度为64。
description 字符串 否 函数功能的描述，模型用它来选择何时以及如何调用函数。
parameters 对象 否 函数接受的参数，描述为JSON Schema对象。请参阅指南获取示例，以及JSON Schema参考了解格式文档。省略parameters定义一个空参数列表的函数。
strict 布尔值或 null 否 默认值：false。是否在生成函数调用时启用严格架构遵守。如果设置为 true，模型将遵循 parameters 字段中定义的确切架构。strict 为 true 时，仅支持 JSON Schema 的子集。详情请参阅函数调用指南中的结构化输出部分。

functions

模型可能生成 JSON 输入的函数列表。

属性 类型 必需 描述
name 字符串 是 要调用的函数名称。必须是a-z、A-Z、0-9，或包含下划线和破折号，最大长度为64。
description 字符串 否 函数功能的描述，模型用它来选择何时以及如何调用函数。
parameters 对象 否 函数接受的参数，描述为JSON Schema对象。省略parameters定义一个空参数列表的函数。

tool_choice

控制模型调用哪个工具（如果有）：

当没有工具时默认为 none，有工具时默认为 auto。

可能的类型：

类型 描述
字符串 none 表示模型不会调用任何工具，而是生成消息。auto 表示模型可以在生成消息或调用一个或多个工具之间选择。required 表示模型必须调用一个或多个工具。
对象 指定模型应使用的工具。用于强制模型调用特定函数。

对象属性：

属性 类型 必需 描述
function 对象 是 包含函数信息的对象
type 字符串 是 工具的类型。目前，仅支持 function。

function 属性：

属性 类型 必需 描述
name 字符串 是 要调用的函数名称。

function_call

控制模型调用哪个函数（如果有）：

对象类型属性：

属性 类型 必需 描述
name 字符串 是 要调用的函数名称。

parallel_tool_calls

是否在工具使用期间启用并行函数调用。

stream

如果设置为 true，模型响应数据将在生成时通过服务器发送事件流式传输到客户端。请参阅下方的流式响应部分获取更多信息，以及流式响应指南了解如何处理流式事件。

top_logprobs

0 到 20 之间的整数，指定在每个标记位置返回的最可能标记的数量，每个标记都有关联的对数概率。如果使用此参数，必须将 logprobs 设置为 true。

web_search_options

此工具搜索网络以获取相关结果用于回复。了解更多关于网络搜索工具的信息。

可能的属性：

属性 类型 必需 描述
search_context_size 字符串 否 默认值：medium。用于搜索的上下文窗口空间量的高级指导。可选值为 low、medium 或 high。medium 是默认值。
user_location 对象或 null 否 搜索的近似位置参数。

user_location 属性：

属性 类型 必需 描述
approximate 对象 是 搜索的近似位置参数。

approximate 属性：

属性 类型 必需 描述
city 字符串 否 用户城市的自由文本输入，例如 San Francisco。
country 字符串 否 用户的两字母 ISO 国家代码，例如 US。
region 字符串 否 用户地区的自由文本输入，例如 California。
timezone 字符串 否 用户的 IANA 时区，例如 America/Los_Angeles。
type 字符串 是 位置近似类型。始终为 approximate。

📥 响应

聊天补全对象

返回一个聊天补全对象,如果请求被流式传输,则返回聊天补全块对象的流式序列。

id

object

created

model

system_fingerprint

choices

usage

service_tier

聊天补全对象响应示例

{
  "id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG",
  "object": "chat.completion",
  "created": 1741570283,
  "model": "gpt-4o-2024-08-06",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "图片展示了一条穿过茂密绿色草地或草甸的木制栈道。天空湛蓝，点缀着几朵散落的云彩，给整个场景营造出宁静祥和的氛围。背景中可以看到树木和灌木丛。",
        "refusal": null,
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1117,
    "completion_tokens": 46,
    "total_tokens": 1163,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "service_tier": "default",
  "system_fingerprint": "fp_fc9f1d7035"
}

聊天补全列表对象

当返回多个聊天补全时，API 可能会返回聊天补全列表对象。

object

data

first_id

last_id

has_more

聊天补全列表响应示例

{
  "object": "list",
  "data": [
    {
      "object": "chat.completion",
      "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2",
      "model": "gpt-4o-2024-08-06",
      "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": "电路之心低吟，\n在寂静中学习模式—\n未来的宁静火花。",
            "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
}

聊天补全消息列表对象

聊天补全消息列表对象表示聊天消息的列表。

object

data

first_id

last_id

has_more

聊天补全消息列表响应示例

{
  "object": "list",
  "data": [
    {
      "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0",
      "role": "user",
      "content": "写一首关于人工智能的俳句",
      "name": null,
      "content_parts": null
    }
  ],
  "first_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0",
  "last_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0",
  "has_more": false
}

OpenAI 响应格式（Responses）

官方文档

📝 简介

OpenAI 最先进的模型响应接口。支持文本和图像输入，以及文本输出。创建与模型的有状态交互，将先前响应的输出用作输入。通过文件搜索、网络搜索、计算机使用等内置工具扩展模型的能力。使用函数调用允许模型访问外部系统和数据。

相关指南可参阅OpenAI官网：Responses

💡 请求示例

基础文本响应 ✅

curl https://$Burncloud_API_BaseUrl/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $Burncloud_API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "input": "讲一个三句话的关于独角兽的睡前故事。"
  }'

响应示例:

{
  "id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b",
  "object": "response",
  "created_at": 1741476542,
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "gpt-4.1",
  "output": [
    {
      "type": "message",
      "id": "msg_67ccd2bf17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "在一个宁静的月夜下，一只名叫璐米娜的独角兽发现了一个倒映着星星的隐藏水池。当她将独角浸入水中时，水池开始闪烁，显现出通往一个有着无尽夜空的魔法世界的路径。充满好奇，璐米娜为所有做梦的人许下愿望，希望他们能找到自己的隐藏魔法，当她回头望去，她的蹄印像星尘一样闪烁。",
          "annotations": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "store": true,
  "temperature": 1.0,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1.0,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 36,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 87,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 123
  },
  "user": null,
  "metadata": {}
}

图像分析响应 ✅

curl https://$Burncloud_API_BaseUrl/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $Burncloud_API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "input": [
      {
        "role": "user",
        "content": [
          {"type": "input_text", "text": "描述这张图片中的内容"},
          {
            "type": "input_image",
            "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
          }
        ]
      }
    ]
  }'

响应示例:

{
  "id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41",
  "object": "response",
  "created_at": 1741476777,
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "gpt-4.1",
  "output": [
    {
      "type": "message",
      "id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "这张图片展示了一条木制栈道或小径穿过茂密的绿色草地，上方是点缀着几朵云的蓝天。场景呈现出一个宁静的自然区域，可能是公园或自然保护区。背景中有树木和灌木丛。整个景观展现出和谐的自然环境，栈道为游客提供了一条穿过湿地或草原而不影响周围生态系统的路径。",
          "annotations": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "store": true,
  "temperature": 1.0,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1.0,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 328,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 52,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 380
  },
  "user": null,
  "metadata": {}
}

网络搜索工具 ✅

curl https://$Burncloud_API_BaseUrl/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $Burncloud_API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "tools": [{ "type": "web_search_preview" }],
    "input": "今天有什么积极正面的新闻?"
  }'

响应示例:

{
  "id": "resp_67ccf18ef5fc8190b16dbee19bc54e5f087bb177ab789d5c",
  "object": "response",
  "created_at": 1741484430,
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "gpt-4.1",
  "output": [
    {
      "type": "web_search_call",
      "id": "ws_67ccf18f64008190a39b619f4c8455ef087bb177ab789d5c",
      "status": "completed"
    },
    {
      "type": "message",
      "id": "msg_67ccf190ca3881909d433c50b1f6357e087bb177ab789d5c",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "截至今天，2025年3月9日，一则值得关注的积极新闻是中国科学家在可再生能源领域取得重大突破，成功研发出一种新型高效太阳能电池，转化率达到了创纪录的35%，这可能会极大推动清洁能源的普及和应用。这项技术预计将使太阳能发电成本降低约40%，为全球减少碳排放提供了新的解决方案。",
          "annotations": [
            {
              "type": "url_citation",
              "start_index": 42,
              "end_index": 100,
              "url": "https://example.com/renewable-energy-breakthrough/?utm_source=chatgpt.com",
              "title": "中国科学家在可再生能源领域取得重大突破"
            },
            {
              "type": "url_citation",
              "start_index": 101,
              "end_index": 150,
              "url": "https://example.com/solar-cell-efficiency-record/?utm_source=chatgpt.com",
              "title": "新型高效太阳能电池转化率创纪录"
            },
            {
              "type": "url_citation",
              "start_index": 151,
              "end_index": 200,
              "url": "https://example.com/clean-energy-cost-reduction/?utm_source=chatgpt.com",
              "title": "太阳能发电成本有望降低40%"
            }
          ]
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "store": true,
  "temperature": 1.0,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [
    {
      "type": "web_search_preview",
      "domains": [],
      "search_context_size": "medium",
      "user_location": {
        "type": "approximate",
        "city": null,
        "country": "US",
        "region": null,
        "timezone": null
      }
    }
  ],
  "top_p": 1.0,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 328,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 356,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 684
  },
  "user": null,
  "metadata": {}
}

文件搜索工具 ✅

curl https://$Burncloud_API_BaseUrl/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $Burncloud_API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "tools": [{
      "type": "file_search",
      "vector_store_ids": ["vs_1234567890"],
      "max_num_results": 20
    }],
    "input": "古代棕龙有哪些特性和属性?"
  }'

响应示例:

{
  "id": "resp_67ccf4c55fc48190b71bd0463ad3306d09504fb6872380d7",
  "object": "response",
  "created_at": 1741485253,
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "gpt-4.1",
  "output": [
    {
      "type": "file_search_call",
      "id": "fs_67ccf4c63cd08190887ef6464ba5681609504fb6872380d7",
      "status": "completed",
      "queries": [
        "古代棕龙的特性和属性"
      ],
      "results": null
    },
    {
      "type": "message",
      "id": "msg_67ccf4c93e5c81909d595b369351a9d309504fb6872380d7",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "根据资料，古代棕龙具有以下特性和属性：\n\n1. 物理特征：古代棕龙体型庞大，体长可达25-30米，翼展约35米。它们的鳞片呈深棕色至铜色，随着年龄增长会变得更加暗沉。头部有特征性的双角和脊刺，下颚强壮，适合撕裂猎物。\n\n2. 能力：它们能喷吐强力的酸液，对目标造成严重腐蚀伤害。古代棕龙还拥有出色的掘地能力，常在沙漠或山地挖掘复杂的巢穴系统。\n\n3. 智力：被认为是龙族中最为狡猾和有耐心的品种，智力极高，精通多种语言，并具有复杂的战术思维。\n\n4. 栖息地：主要栖息在干旱的山地和沙漠地区，喜欢炎热干燥的环境。\n\n5. 宝藏：古代棕龙以其庞大的宝藏闻名，特别喜爱收集铜币、红宝石和火焰魔法物品。\n\n6. 寿命：是所有龙种中寿命最长的之一，可活2000-2500年，随着年龄增长其力量和魔法能力也会增强。\n\n7. 性格：极度领地意识强，性格暴躁易怒，对侵入者毫不留情，但也以其罕见的耐心著称，能为复仇等待几个世纪。",
          "annotations": [
            {
              "type": "file_citation",
              "index": 80,
              "file_id": "file-4wDz5b167pAf72nx1h9eiN",
              "filename": "dragons.pdf"
            },
            {
              "type": "file_citation",
              "index": 233,
              "file_id": "file-4wDz5b167pAf72nx1h9eiN",
              "filename": "dragons.pdf"
            },
            {
              "type": "file_citation",
              "index": 345,
              "file_id": "file-4wDz5b167pAf72nx1h9eiN",
              "filename": "dragons.pdf"
            },
            {
              "type": "file_citation",
              "index": 420,
              "file_id": "file-4wDz5b167pAf72nx1h9eiN",
              "filename": "dragons.pdf"
            },
            {
              "type": "file_citation",
              "index": 520,
              "file_id": "file-4wDz5b167pAf72nx1h9eiN",
              "filename": "dragons.pdf"
            },
            {
              "type": "file_citation",
              "index": 580,
              "file_id": "file-4wDz5b167pAf72nx1h9eiN",
              "filename": "dragons.pdf"
            },
            {
              "type": "file_citation",
              "index": 655,
              "file_id": "file-4wDz5b167pAf72nx1h9eiN",
              "filename": "dragons.pdf"
            },
            {
              "type": "file_citation",
              "index": 781,
              "file_id": "file-4wDz5b167pAf72nx1h9eiN",
              "filename": "dragons.pdf"
            }
          ]
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "store": true,
  "temperature": 1.0,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [
    {
      "type": "file_search",
      "filters": null,
      "max_num_results": 20,
      "ranking_options": {
        "ranker": "auto",
        "score_threshold": 0.0
      },
      "vector_store_ids": [
        "vs_1234567890"
      ]
    }
  ],
  "top_p": 1.0,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 18307,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 348,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 18655
  },
  "user": null,
  "metadata": {}
}

流式响应 ✅

curl https://$Burncloud_API_BaseUrl/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $Burncloud_API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "instructions": "你是一个有帮助的助手。",
    "input": "你好！",
    "stream": true
  }'

流式响应示例:

event: response.created
data: {"type":"response.created","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"你是一个有帮助的助手。","max_output_tokens":null,"model":"gpt-4.1-2025-04-14","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}}

event: response.in_progress
data: {"type":"response.in_progress","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"你是一个有帮助的助手。","max_output_tokens":null,"model":"gpt-4.1-2025-04-14","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}}

event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"in_progress","role":"assistant","content":[]}}

event: response.content_part.added
data: {"type":"response.content_part.added","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"","annotations":[]}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"你好"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"！"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":" 我"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"能"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"为"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"您"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"提供"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"什么"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"帮助"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"吗"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"？"}

event: response.output_text.done
data: {"type":"response.output_text.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"text":"你好！ 我能为您提供什么帮助吗？"}

event: response.content_part.done
data: {"type":"response.content_part.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"你好！ 我能为您提供什么帮助吗？","annotations":[]}}

event: response.output_item.done
data: {"type":"response.output_item.done","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"你好！ 我能为您提供什么帮助吗？","annotations":[]}]}}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"completed","error":null,"incomplete_details":null,"instructions":"你是一个有帮助的助手。","max_output_tokens":null,"model":"gpt-4.1-2025-04-14","output":[{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"你好！ 我能为您提供什么帮助吗？","annotations":[]}]}],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":{"input_tokens":37,"output_tokens":11,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":48},"user":null,"metadata":{}}}

函数调用 ✅

curl https://$Burncloud_API_BaseUrl/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $Burncloud_API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "input": "波士顿今天的天气如何？",
    "tools": [
      {
        "type": "function",
        "name": "get_current_weather",
        "description": "获取指定位置的当前天气",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "城市和州，例如 San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"]
            }
          },
          "required": ["location", "unit"]
        }
      }
    ],
    "tool_choice": "auto"
  }'

响应示例:

{
  "id": "resp_67ca09c5efe0819096d0511c92b8c890096610f474011cc0",
  "object": "response",
  "created_at": 1741294021,
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "gpt-4.1-2025-04-14",
  "output": [
    {
      "type": "function_call",
      "id": "fc_67ca09c6bedc8190a7abfec07b1a1332096610f474011cc0",
      "call_id": "call_unLAR8MvFNptuiZK6K6HCy5k",
      "name": "get_current_weather",
      "arguments": "{\"location\":\"波士顿, MA\",\"unit\":\"celsius\"}",
      "status": "completed"
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "store": true,
  "temperature": 1.0,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [
    {
      "type": "function",
      "description": "获取指定位置的当前天气",
      "name": "get_current_weather",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "城市和州，例如 San Francisco, CA"
          },
          "unit": {
            "type": "string",
            "enum": [
              "celsius",
              "fahrenheit"
            ]
          }
        },
        "required": [
          "location",
          "unit"
        ]
      },
      "strict": true
    }
  ],
  "top_p": 1.0,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 291,
    "output_tokens": 23,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 314
  },
  "user": null,
  "metadata": {}
}

推理能力 ✅

curl https://$Burncloud_API_BaseUrl/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $Burncloud_API_KEY" \
  -d '{
    "model": "o3-mini",
    "input": "一只啄木鸟能啄多少木头?",
    "reasoning": {
      "effort": "high"
    }
  }'

响应示例:

{
  "id": "resp_67ccd7eca01881908ff0b5146584e408072912b2993db808",
  "object": "response",
  "created_at": 1741477868,
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "o1-2024-12-17",
  "output": [
    {
      "type": "message",
      "id": "msg_67ccd7f7b5848190a6f3e95d809f6b44072912b2993db808",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "这是一个源自英文绕口令"How much wood would a woodchuck chuck if a woodchuck could chuck wood"的问题。在现实中，啄木鸟(woodpecker)和土拨鼠(woodchuck)是不同的动物，而且土拨鼠实际上并不"啄(chuck)"木头。\n\n从科学角度看，啄木鸟每天确实会啄树木以寻找食物、建造巢穴或进行通讯。一只啄木鸟平均每天可能啄树约8000-12000次，视物种和具体目的而定。如果我们将这转换为木材量，假设每次啄击移除约0.1-0.2立方厘米的木材，那么一只啄木鸟理论上每天可能移除约800-2400立方厘米的木材。\n\n然而，啄木鸟主要是为了觅食和筑巢而啄木，而不是单纯地移除木材，所以这个计算只是一个有趣的理论估算。",
          "annotations": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "reasoning": {
    "effort": "high",
    "summary": null
  },
  "store": true,
  "temperature": 1.0,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1.0,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 81,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 1035,
    "output_tokens_details": {
      "reasoning_tokens": 832
    },
    "total_tokens": 1116
  },
  "user": null,
  "metadata": {}
}

📮 请求

端点

POST /v1/responses

创建模型响应。提供文本或图像输入以生成文本或JSON输出。让模型调用您自己的自定义代码或使用内置工具（如网络搜索或文件搜索）将您自己的数据用作模型响应的输入。

鉴权方法

在请求头中包含以下内容进行 API 密钥认证：

Authorization: Bearer $Burncloud_API_KEY

其中 $Burncloud_API_KEY 是您的 API 密钥。

请求体参数

input

类型: 字符串或数组
必需: 是

提供给模型的文本、图像或文件输入，用于生成响应。

可能的类型
类型 描述
字符串 文本输入，相当于具有用户角色的文本输入
输入项数组 包含不同内容类型的一个或多个输入项列表
输入消息对象
属性 类型 必需 描述
content 字符串或数组 是 提供给模型的文本、图像或音频输入，用于生成响应。也可以包含之前的助手响应
role 字符串 是 输入消息的角色。可选值：user、assistant、system 或 developer
type 字符串 否 输入消息的类型，始终为 message
内容项类型
文本输入
属性 类型 必需 描述
text 字符串 是 提供给模型的文本输入
type 字符串 是 输入项的类型，始终为 input_text
图像输入
属性 类型 必需 描述
detail 字符串 是 要发送给模型的图像的详细级别。可选值：high、low 或 auto。默认为 auto
type 字符串 是 输入项的类型，始终为 input_image
file_id 字符串 否 要发送给模型的文件ID
image_url 字符串 否 要发送给模型的图像URL。可以是完整的URL或数据URL中的base64编码图像
文件输入
属性 类型 必需 描述
type 字符串 是 输入项的类型，始终为 input_file
file_data 字符串 否 要发送给模型的文件内容
file_id 字符串 否 要发送给模型的文件ID
filename 字符串 否 要发送给模型的文件名
输出项类型
输出文本
属性 类型 必需 描述
text 字符串 是 模型生成的文本输出
type 字符串 是 输出项的类型，始终为 output_text
annotations 数组 是 文本输出的注释
注释类型

文件引用:

属性 类型 必需 描述
file_id 字符串 是 文件的ID
index 整数 是 文件在文件列表中的索引
type 字符串 是 文件引用的类型，始终为 file_citation

URL引用:

属性 类型 必需 描述
end_index 整数 是 URL引用在消息中的最后一个字符的索引
start_index 整数 是 URL引用在消息中的第一个字符的索引
title 字符串 是 网络资源的标题
type 字符串 是 URL引用的类型，始终为 url_citation
url 字符串 是 网络资源的URL

文件路径:

属性 类型 必需 描述
file_id 字符串 是 文件的ID
index 整数 是 文件在文件列表中的索引
type 字符串 是 文件路径的类型，始终为 file_path
拒绝响应
属性 类型 必需 描述
refusal 字符串 是 模型的拒绝解释
type 字符串 是 拒绝的类型，始终为 refusal
工具调用类型
文件搜索工具调用
属性 类型 必需 描述
id 字符串 是 文件搜索工具调用的唯一ID
queries 数组 是 用于搜索文件的查询
status 字符串 是 文件搜索工具调用的状态。可能值包括：in_progress、searching、incomplete 或 failed
type 字符串 是 文件搜索工具调用的类型，始终为 file_search_call
results 数组或null 否 文件搜索工具调用的结果
网络搜索工具调用
属性 类型 必需 描述
id 字符串 是 网络搜索工具调用的唯一ID
status 字符串 是 网络搜索工具调用的状态
type 字符串 是 网络搜索工具调用的类型，始终为 web_search_call
函数工具调用
属性 类型 必需 描述
arguments 字符串 是 传递给函数的参数的JSON字符串
call_id 字符串 是 模型生成的函数工具调用的唯一ID
name 字符串 是 要运行的函数的名称
type 字符串 是 函数工具调用的类型，始终为 function_call
id 字符串 否 函数工具调用的唯一ID
status 字符串 否 项目的状态。可能值：in_progress、completed或incomplete
计算机工具调用
属性 类型 必需 描述
action 对象 是 计算机交互的操作，如点击、拖拽等
call_id 字符串 是 响应工具调用输出时使用的标识符
id 字符串 是 计算机调用的唯一ID
pending_safety_checks 数组 是 计算机调用的待处理安全检查
status 字符串 是 项目的状态。可能值：in_progress、completed或incomplete
type 字符串 是 计算机调用的类型，始终为 computer_call

计算机操作类型:

操作类型 描述
click 鼠标点击操作
double_click 鼠标双击操作
drag 拖拽操作
keypress 按键操作
move 鼠标移动操作
screenshot 屏幕截图操作
scroll 滚动操作
type 文本输入操作
wait 等待操作
计算机工具调用输出
属性 类型 必需 描述
call_id 字符串 是 产生输出的计算机工具调用的ID
output 对象 是 用于计算机使用工具的计算机屏幕截图图像
type 字符串 是 计算机工具调用输出的类型，始终为 computer_call_output
acknowledged_safety_checks 数组 否 API报告的已被开发者确认的安全检查
id 字符串 否 计算机工具调用输出的ID
status 字符串 否 输入消息的状态。可能值：in_progress、completed或incomplete
函数工具调用输出
属性 类型 必需 描述
call_id 字符串 是 模型生成的函数工具调用的唯一ID
output 字符串 是 函数工具调用输出的JSON字符串
type 字符串 是 函数工具调用输出的类型，始终为 function_call_output
id 字符串 否 函数工具调用输出的唯一ID
status 字符串 否 项目的状态。可能值：in_progress、completed或incomplete
推理相关项
属性 类型 必需 描述
id 字符串 是 推理内容的唯一标识符
summary 数组 是 推理文本内容
type 字符串 是 对象的类型，始终为 reasoning
encrypted_content 字符串或null 否 推理项的加密内容 - 当使用 reasoning.encrypted_content 包含参数生成响应时填充
status 字符串 否 项目的状态。可能值：in_progress、completed或incomplete

推理摘要:

属性 类型 必需 描述
text 字符串 是 模型生成响应时使用的推理的简短摘要
type 字符串 是 对象的类型，始终为 summary_text
项目引用
属性 类型 必需 描述
id 字符串 是 要引用的项目的ID
type 字符串 否 要引用的项目类型，始终为 item_reference

model

类型: 字符串
必需: 是

用于生成响应的模型ID，例如 gpt-4.1 或 o3。OpenAI 提供各种具有不同能力、性能特性和价格点的模型。请参阅模型指南以浏览和比较可用模型。

include

类型: 数组或null
必需: 否

指定要在模型响应中包含的附加输出数据。当前支持的值包括：

值 描述
file_search_call.results 包含文件搜索工具调用的搜索结果
message.input_image.image_url 包含输入消息中的图像URL
computer_call_output.output.image_url 包含电脑调用输出中的图像URL
reasoning.encrypted_content 在推理项输出中包含推理标记的加密版本

instructions

类型: 字符串或null
必需: 否

作为模型上下文中的第一项插入系统（或开发者）消息。

当与 previous_response_id 一起使用时，前一个响应中的指令不会被带到下一个响应。这使得在新响应中轻松切换系统（开发者）消息变得简单。

max_output_tokens

类型: 整数或null
必需: 否

可以为响应生成的令牌数量的上限，包括可见输出令牌和推理令牌。

metadata

类型: 对象
必需: 否

可以附加到对象的16个键值对集合。这对于以结构化格式存储对象的其他信息很有用,并可以通过 API 或仪表板查询对象。

键是最大长度为64个字符的字符串。值是最大长度为512个字符的字符串。

parallel_tool_calls

类型: 布尔值或null
必需: 否
默认值: true

是否允许模型并行运行工具调用。

previous_response_id

类型: 字符串或null
必需: 否

模型的前一个响应的唯一ID。使用此参数创建多轮对话。了解更多关于对话状态。

reasoning

类型: 对象或null
必需: 否
仅适用于o系列模型

推理模型的配置选项。

属性 类型 必需 描述
effort 字符串或null 否 推理的努力程度，可选值: low, medium, high。默认值为 medium。降低推理努力可以加快响应速度并减少响应中用于推理的令牌数
summary 字符串或null 否 模型执行的推理摘要。这对于调试和理解模型的推理过程很有用。可选值: auto, concise, detailed
generate_summary 字符串或null 否 已弃用: 请使用 summary 替代。模型执行的推理摘要。可选值: auto, concise, detailed

service_tier

类型: 字符串或null
必需: 否
默认值: auto

指定用于处理请求的延迟层级。此参数与订阅了 scale tier 服务的客户相关：

值 描述
auto 如果项目启用了 Scale tier，系统将使用 scale tier 信用直到用完；如果项目未启用 Scale tier，请求将使用默认服务层级处理，具有较低的正常运行时间 SLA 且无延迟保证
default 请求将使用默认服务层级处理，具有较低的正常运行时间 SLA 且无延迟保证
flex 请求将使用 Flex Processing 服务层级处理。了解更多信息请参阅官方文档

当未设置此参数时，默认行为为 auto。

当设置此参数时，响应体将包含已使用的 service_tier。

store

类型: 布尔值或null
必需: 否
默认值: true

是否存储生成的模型响应以供以后通过 API 检索。

stream

类型: 布尔值或null
必需: 否
默认值: false

如果设置为 true，模型响应数据将在生成时使用服务器发送的事件流式传输到客户端。

temperature

类型: 数字或null
必需: 否
默认值: 1

要使用的采样温度，介于 0 和 2 之间。较高的值（如0.8）会使输出更加随机，而较低的值（如0.2）会使其更加集中和确定性。我们通常建议更改此值或 top_p，但不要同时更改。

text

类型: 对象
必需: 否

模型文本响应的配置选项。可以是纯文本或结构化JSON数据。

属性 类型 必需 描述
format 对象 否 指定模型必须输出的格式

配置 { "type": "json_schema" } 启用结构化输出，确保模型将匹配您提供的JSON模式。更多信息请参阅结构化输出指南。

默认格式为 { "type": "text" }，没有其他选项。

不推荐用于gpt-4o及更新的模型： 设置为 { "type": "json_object" } 启用较旧的JSON模式，确保模型生成的消息是有效的JSON。对于支持的模型，首选使用 json_schema。

文本格式类型
文本 (Text)
属性 类型 必需 描述
type 字符串 是 定义的响应格式类型。始终为 text
JSON模式 (JSON Schema)
属性 类型 必需 描述
name 字符串 是 响应格式的名称。必须包含a-z, A-Z, 0-9，或包含下划线和破折号，最大长度为64
schema 对象 是 响应格式的模式，描述为JSON Schema对象
type 字符串 是 定义的响应格式类型。始终为 json_schema
description 字符串 否 响应格式用途的描述，模型用它来确定如何以该格式响应
strict 布尔值或null 否 是否在生成输出时启用严格模式遵循。默认为 false。如果设置为 true，模型将始终遵循 schema 字段中定义的确切模式。严格模式下只支持JSON Schema的子集
JSON对象 (JSON Object)
属性 类型 必需 描述
type 字符串 是 定义的响应格式类型。始终为 json_object

注意：如果没有指示模型这样做的系统或用户消息，模型将不会生成JSON。对于支持的模型，建议使用 json_schema。

tool_choice

类型: 字符串或对象
必需: 否

模型如何选择生成响应时使用的工具（或多个工具）。请参阅 tools 参数了解如何指定模型可以调用的工具。

可能的类型
工具选择模式 (Tool choice mode)

类型: 字符串

控制模型是否调用工具以及调用哪种工具。

值 描述
none 模型不会调用任何工具，而是生成一条消息
auto 模型可以在生成消息或调用一个或多个工具之间选择
required 模型必须调用一个或多个工具
托管工具 (Hosted tool)

类型: 对象

指示模型应使用内置工具生成响应。

属性 类型 必需 描述
type 字符串 是 模型应使用的托管工具类型。允许的值有：file_search、web_search_preview、computer_use_preview
函数工具 (Function tool)

类型: 对象

使用此选项强制模型调用特定函数。

属性 类型 必需 描述
name 字符串 是 要调用的函数名称
type 字符串 是 对于函数调用，类型始终为 function

tools

类型: 数组
必需: 否

模型在生成响应时可能调用的工具数组。你可以通过设置 tool_choice 参数来指定使用哪个工具。

你可以提供给模型的两类工具是：

文件搜索工具 (File search)

类型: 对象

一个搜索已上传文件中相关内容的工具。

属性 类型 必需 描述
type 字符串 是 文件搜索工具的类型，始终为 file_search
vector_store_ids 数组 是 要搜索的向量存储ID列表
filters 对象 否 要应用的过滤器
max_num_results 整数 否 返回的最大结果数。此数字应介于1到50之间（含）
ranking_options 对象 否 搜索排名选项
过滤器类型

比较过滤器 (Comparison Filter)

属性 类型 必需 描述
key 字符串 是 要与值进行比较的键
type 字符串 是 指定比较运算符: eq, ne, gt, gte, lt, lte
- eq: 等于
- ne: 不等于
- gt: 大于
- gte: 大于等于
- lt: 小于
- lte: 小于等于
value 字符串/数字/布尔值 是 要与属性键比较的值；支持字符串、数字或布尔类型

复合过滤器 (Compound Filter)

属性 类型 必需 描述
filters 数组 是 要组合的过滤器数组。项目可以是比较过滤器或复合过滤器
type 字符串 是 操作类型: and 或 or
排名选项
属性 类型 必需 描述
ranker 字符串 否 文件搜索使用的排名器
score_threshold 数字 否 文件搜索的分数阈值，介于0和1之间的数字。接近1的数字将尝试仅返回最相关的结果，但可能返回更少的结果
函数工具 (Function)

类型: 对象

定义模型可以选择调用的您自己代码中的函数。

属性 类型 必需 描述
type 字符串 是 函数工具的类型，始终为 function
name 字符串 是 要调用的函数名称
parameters 对象 是 描述函数参数的JSON模式对象
strict 布尔值 是 是否强制严格参数验证。默认为 true
description 字符串 否 函数的描述。模型用它来确定是否调用函数
网络搜索工具 (Web search preview)

类型: 对象

此工具搜索网络上的相关结果，用于响应。

属性 类型 必需 描述
type 字符串 是 网络搜索工具的类型。可选值: web_search_preview 或 web_search_preview_2025_03_11
search_context_size 字符串 否 对用于搜索的上下文窗口空间量的高级指导。可选值: low, medium, high。默认为 medium
user_location 对象 否 用户的位置
domains 数组 否 限制搜索的域名列表
用户位置
属性 类型 必需 描述
type 字符串 是 位置近似类型。始终为 approximate
city 字符串 否 用户所在城市的自由文本输入，例如 "San Francisco"
country 字符串 否 用户的两字母ISO国家代码，例如 "US"
region 字符串 否 用户所在区域的自由文本输入，例如 "California"
timezone 字符串 否 用户的IANA时区，例如 "America/Los_Angeles"
计算机使用工具 (Computer use preview)

类型: 对象

控制虚拟计算机的工具。

属性 类型 必需 描述
type 字符串 是 计算机使用工具的类型。始终为 computer_use_preview
display_height 整数 是 计算机显示器的高度
display_width 整数 是 计算机显示器的宽度
environment 字符串 是 要控制的计算机环境类型

top_p

类型: 数字或null
必需: 否
默认值: 1

一种替代采样温度的方法，称为核采样，其中模型考虑具有 top_p 概率质量的标记结果。因此，0.1 意味着只考虑包含前 10% 概率质量的标记。

我们通常建议更改此值或 temperature，但不要同时更改。

truncation

类型: 字符串或null
必需: 否
默认值: disabled

用于模型响应的截断策略：

值 描述
auto 如果此响应和前一个响应的上下文超过模型的上下文窗口大小，模型将通过删除对话中间的输入项来截断响应以适应上下文窗口
disabled 如果模型响应将超过模型的上下文窗口大小，请求将失败并显示400错误

user

类型: 字符串
必需: 否

表示最终用户的唯一标识符，可以帮助OpenAI监控和检测滥用行为。

📥 响应

返回一个响应对象。

成功响应

返回一个响应对象，如果请求被流式传输，则返回响应对象的流式序列。

id

object

created_at

status

error

incomplete_details

instructions

max_output_tokens

model

output

parallel_tool_calls

previous_response_id

reasoning

store

temperature

text

tool_choice

tools

top_p

truncation

usage

user

metadata

Anthropic 对话格式（Messages）

官方文档

📝 简介

给定一组包含文本和/或图像内容的结构化输入消息列表，模型将生成对话中的下一条消息。Messages API 可用于单次查询或无状态的多轮对话。

💡 请求示例

基础文本对话 ✅

curl https://$Burncloud_API_BaseUrl/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $Burncloud_API_KEY" \
     --data \
'{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, world"}
    ]
}'

响应示例:

{
  "content": [
    {
      "text": "Hi! My name is Claude.",
      "type": "text"
    }
  ],
  "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
  "model": "claude-3-5-sonnet-20241022", 
  "role": "assistant",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 2095,
    "output_tokens": 503
  }
}

图像分析对话 ✅

curl https://$Burncloud_API_BaseUrl/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $Burncloud_API_KEY" \
     --data \
'{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/jpeg",
                        "data": "/9j/4AAQSkZJRg..."
                    }
                },
                {
                    "type": "text",
                    "text": "这张图片里有什么?"
                }
            ]
        }
    ]
}'

响应示例:

{
  "content": [
    {
      "text": "这张图片显示了一只橙色的猫咪正在窗台上晒太阳。猫咪看起来很放松，眯着眼睛享受阳光。窗外可以看到一些绿色的植物。",
      "type": "text"
    }
  ],
  "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
  "model": "claude-3-5-sonnet-20241022",
  "role": "assistant",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 3050,
    "output_tokens": 892
  }
}

工具调用 ✅

curl https://$Burncloud_API_BaseUrl/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $Burncloud_API_KEY" \
     --data \
'{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [
        {
            "role": "user", 
            "content": "今天北京的天气怎么样?"
        }
    ],
    "tools": [
        {
            "name": "get_weather",
            "description": "获取指定位置的当前天气",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "城市名称,如:北京"
                    }
                },
                "required": ["location"]
            }
        }
    ]
}'

响应示例:

{
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
      "name": "get_weather",
      "input": { "location": "北京" }
    }
  ],
  "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
  "model": "claude-3-5-sonnet-20241022",
  "role": "assistant",
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 2156,
    "output_tokens": 468
  }
}

流式响应 ✅

curl https://$Burncloud_API_BaseUrl/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $Burncloud_API_KEY" \
     --data \
'{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [
        {
            "role": "user",
            "content": "讲个故事"
        }
    ],
    "stream": true
}'

响应示例:

{
  "type": "message_start",
  "message": {
    "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
    "model": "claude-3-5-sonnet-20241022",
    "role": "assistant",
    "type": "message"
  }
}
{
  "type": "content_block_start",
  "index": 0,
  "content_block": {
    "type": "text"
  }
}
{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "text": "从前"
  }
}
{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "text": "有一只"
  }
}
{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "text": "小兔子..."
  }
}
{
  "type": "content_block_stop",
  "index": 0
}
{
  "type": "message_delta",
  "delta": {
    "stop_reason": "end_turn",
    "usage": {
      "input_tokens": 2045,
      "output_tokens": 628
    }
  }
}
{
  "type": "message_stop"
}

📮 请求

端点

POST /v1/messages

鉴权方法

在请求头中包含以下内容进行 API 密钥认证：

x-api-key: $Burncloud_API_KEY

其中 $Burncloud_API_KEY 是您的 API 密钥。您可以通过控制台获取 API 密钥，每个密钥仅限于一个工作区使用。

请求头参数

anthropic-beta

指定要使用的 beta 版本，支持用逗号分隔的列表如 beta1,beta2，或多次指定该请求头。

anthropic-version

指定要使用的 API 版本。

请求体参数

max_tokens

生成的最大 token 数量。不同模型有不同的限制，详见模型文档。范围 x > 1。

messages

输入消息列表。模型被训练为在用户和助手之间交替进行对话。创建新消息时，您可以使用 messages 参数指定之前的对话轮次，模型将生成对话中的下一条消息。连续的用户或助手消息会被合并为单个轮次。

每个消息必须包含 role 和 content 字段。您可以指定单个用户角色消息，或包含多个用户和助手消息。如果最后一条消息使用助手角色，响应内容将直接从该消息的内容继续，这可以用来约束模型的响应。

单条用户消息示例:

[{"role": "user", "content": "Hello, Claude"}]

多轮对话示例:

[
  {"role": "user", "content": "你好。"},
  {"role": "assistant", "content": "你好！我是 Claude。有什么可以帮你的吗？"},
  {"role": "user", "content": "请用简单的话解释什么是 LLM？"}
]

部分填充的响应示例:

[
  {"role": "user", "content": "太阳的希腊语名字是什么? (A) Sol (B) Helios (C) Sun"},
  {"role": "assistant", "content": "正确答案是 ("}
]

每个消息的 content 可以是字符串或内容块数组。使用字符串相当于一个 "text" 类型的内容块数组的简写。以下两种写法等效：

{"role": "user", "content": "Hello, Claude"}

{
  "role": "user", 
  "content": [{"type": "text", "text": "Hello, Claude"}]
}

从 Claude 3 模型开始，您还可以发送图片内容块：

{
  "role": "user",
  "content": [
    {
      "type": "image",
      "source": {
        "type": "base64",
        "media_type": "image/jpeg",
        "data": "/9j/4AAQSkZJRg..."
      }
    },
    {
      "type": "text",
      "text": "这张图片里有什么?"
    }
  ]
}

目前支持的图片格式包括: base64, image/jpeg、image/png、image/gif 和 image/webp。

messages.role

注意：Messages API 中没有 "system" 角色，如果需要系统提示，请使用顶层的 system 参数。

messages.content

消息内容可以是以下几种类型之一：

文本内容 (Text)
{
  "type": "text",          // 必需，枚举值: "text"
  "text": "Hello, Claude", // 必需，最小长度: 1
  "cache_control": {
    "type": "ephemeral"    // 可选，枚举值: "ephemeral"
  }
}
图片内容 (Image)
{
  "type": "image",         // 必需，枚举值: "image"
  "source": {             // 必需
    "type": "base64",     // 必需，枚举值: "base64"
    "media_type": "image/jpeg", // 必需，支持: image/jpeg, image/png, image/gif, image/webp
    "data": "/9j/4AAQSkZJRg..."  // 必需，base64 编码的图片数据
  },
  "cache_control": {
    "type": "ephemeral"    // 可选，枚举值: "ephemeral"
  }
}
工具使用 (Tool Use)
{
  "type": "tool_use",      // 必需，枚举值: "tool_use"，默认值
  "id": "toolu_xyz...",    // 必需，工具使用的唯一标识符
  "name": "get_weather",   // 必需，工具名称，最小长度: 1
  "input": {              // 必需，工具的输入参数对象
    // 工具输入参数，具体格式由工具的 input_schema 定义
  },
  "cache_control": {
    "type": "ephemeral"    // 可选，枚举值: "ephemeral"
  }
}
工具结果 (Tool Result)
{
  "type": "tool_result",   // 必需，枚举值: "tool_result"
  "tool_use_id": "toolu_xyz...",  // 必需
  "content": "结果内容",   // 必需，可以是字符串或内容块数组
  "is_error": false,      // 可选，布尔值
  "cache_control": {
    "type": "ephemeral"    // 可选，枚举值: "ephemeral"
  }
}

当 content 为内容块数组时，每个内容块可以是文本或图片：

{
  "type": "tool_result",
  "tool_use_id": "toolu_xyz...",
  "content": [
    {
      "type": "text",      // 必需，枚举值: "text"
      "text": "分析结果",   // 必需，最小长度: 1
      "cache_control": {
        "type": "ephemeral" // 可选，枚举值: "ephemeral"
      }
    },
    {
      "type": "image",     // 必需，枚举值: "image"
      "source": {         // 必需
        "type": "base64", // 必需，枚举值: "base64"
        "media_type": "image/jpeg",
        "data": "..."
      },
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ]
}
文档 (Document)
{
  "type": "document",      // 必需，枚举值: "document"
  "source": {             // 必需
    // 文档源数据
  },
  "cache_control": {
    "type": "ephemeral"    // 可选，枚举值: "ephemeral"
  }
}

注意：

  1. 每种类型都可以包含可选的 cache_control 字段，用于控制内容的缓存行为
  2. 文本内容的最小长度为 1
  3. 所有类型的 type 字段都是必需的枚举字符串
  4. 工具结果的 content 字段支持字符串或包含文本/图片的内容块数组

model

要使用的模型名称，详见模型文档。范围 1 - 256 个字符。

metadata

描述请求元数据的对象。包含以下可选字段：

stop_sequences

自定义的停止生成的文本序列。

stream

是否使用服务器发送事件 (SSE) 来增量返回响应内容。

system

系统 prompt，为 Claude 提供背景和指令。这是一种为模型提供上下文和特定目标或角色的方式。注意这与消息中的 role 不同，Messages API 中没有 "system" 角色。

temperature

控制生成随机性，0.0 - 1.0。范围 0 < x < 1。建议对于分析性/选择题类任务使用接近 0.0 的值，对于创造性和生成性任务使用接近 1.0 的值。

注意：即使 temperature 设置为 0.0，结果也不会完全确定。

🆕 thinking

配置 Claude 的扩展思考功能。启用时，响应将包含展示 Claude 在给出最终答案前的思考过程的内容块。需要至少 1,024 个 token 的预算，并计入您的 max_tokens 限制。

可以设置为以下两种模式之一：

1. 启用模式
{
  "type": "enabled",
  "budget_tokens": 2048
}
2. 禁用模式
{
  "type": "disabled"
}

tool_choice

控制模型如何使用提供的工具。可以是以下三种类型之一：

1. Auto 模式 (自动选择)
{
  "type": "auto",  // 必需，枚举值: "auto"
  "disable_parallel_tool_use": false  // 可选，默认 false。如果为 true，模型最多只会使用一个工具
}
2. Any 模式 (任意工具)
{
  "type": "any",  // 必需，枚举值: "any"
  "disable_parallel_tool_use": false  // 可选，默认 false。如果为 true，模型将恰好使用一个工具
}
3. Tool 模式 (指定工具)
{
  "type": "tool",  // 必需，枚举值: "tool"
  "name": "get_weather",  // 必需，指定要使用的工具名称
  "disable_parallel_tool_use": false  // 可选，默认 false。如果为 true，模型将恰好使用一个工具
}

注意：

  1. Auto 模式：模型可以自行决定是否使用工具
  2. Any 模式：模型必须使用工具，但可以选择任何可用的工具
  3. Tool 模式：模型必须使用指定的工具

tools

定义模型可能使用的工具。工具可以是自定义工具或内置工具类型：

1. 自定义工具（Tool）

每个自定义工具定义包含：

示例：

[
  {
    "type": "custom",
    "name": "get_weather",
    "description": "获取指定位置的当前天气",
    "input_schema": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "城市名称,如:北京"
        }
      },
      "required": ["location"]
    }
  }
]
2. 计算机工具 (ComputerUseTool)
{
  "type": "computer_20241022",  // 必需
  "name": "computer",           // 必需，枚举值: "computer"
  "display_width_px": 1024,     // 必需，显示宽度(像素)
  "display_height_px": 768,     // 必需，显示高度(像素)
  "display_number": 0,          // 可选，X11 显示编号
  "cache_control": {
    "type": "ephemeral"         // 可选
  }
}
3. Bash 工具 (BashTool)
{
  "type": "bash_20241022",      // 必需
  "name": "bash",               // 必需，枚举值: "bash"
  "cache_control": {
    "type": "ephemeral"         // 可选
  }
}
4. 文本编辑器工具 (TextEditor)
{
  "type": "text_editor_20241022", // 必需
  "name": "str_replace_editor",   // 必需，枚举值: "str_replace_editor"
  "cache_control": {
    "type": "ephemeral"           // 可选
  }
}

当模型使用工具时，会返回 tool_use 内容块：

[
  {
    "type": "tool_use",
    "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
    "name": "get_weather",
    "input": { "location": "北京" }
  }
]

您可以执行工具并通过 tool_result 内容块返回结果：

[
  {
    "type": "tool_result",
    "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
    "content": "北京当前天气晴朗，温度 25°C"
  }
]

top_k

从 token 的前 K 个选项中采样。用于移除低概率的"长尾"响应。建议仅在高级用例中使用，通常只需要调整 temperature。

top_p

使用 nucleus 采样。计算每个后续 token 按概率降序排列的累积分布，在达到 top_p 指定的概率时截断。建议仅调整 temperature 或 top_p 其中之一，不要同时使用。

📥 响应

成功响应

返回一个聊天补全对象，包含以下字段：

content

模型生成的内容，由多个内容块组成。每个内容块都有一个确定其形状的 type。内容块可以是以下类型之一：

文本内容块 (Text)
{
  "type": "text",          // 必需，枚举值: "text"，默认值
  "text": "你好，我是 Claude。" // 必需，最大长度: 5000000，最小长度: 1
}
工具使用内容块 (Tool Use)
{
  "type": "tool_use",      // 必需，枚举值: "tool_use"，默认值
  "id": "toolu_xyz...",    // 必需，工具使用的唯一标识符
  "name": "get_weather",   // 必需，工具名称，最小长度: 1
  "input": {              // 必需，工具的输入参数对象
    // 工具输入参数，具体格式由工具的 input_schema 定义
  }
}

示例：

// 文本内容示例
[{"type": "text", "text": "你好，我是 Claude。"}]

// 工具使用示例
[{
  "type": "tool_use",
  "id": "toolu_xyz...",
  "name": "get_weather",
  "input": { "location": "北京" }
}]

// 混合内容示例
[
  {"type": "text", "text": "根据天气查询结果："},
  {
    "type": "tool_use",
    "id": "toolu_xyz...",
    "name": "get_weather",
    "input": { "location": "北京" }
  }
]

如果请求的最后一条消息是助手角色，响应内容会直接从该消息继续。例如：

// 请求
[
  {"role": "user", "content": "太阳的希腊语名字是什么? (A) Sol (B) Helios (C) Sun"},
  {"role": "assistant", "content": "正确答案是 ("}
]

// 响应
[{"type": "text", "text": "B)"}]

id

响应的唯一标识符。

model

使用的模型名称。

role

生成消息的会话角色，始终为 "assistant"。

stop_reason

停止生成的原因，可能的值包括：

在非流式模式下，此值始终非空。在流式模式下，在 message_start 事件中为 null，其他情况下非空。

stop_sequence

生成的自定义停止序列。如果模型遇到了 stop_sequences 参数中指定的某个序列，这个字段将包含该匹配的停止序列。如果不是因为停止序列而停止，则为 null。

type

对象类型，对于 Messages 始终为 "message"。

usage

计费和限流相关的使用量统计。包含以下字段：

注意：由于 API 在内部会对请求进行转换和解析，token 计数可能与请求和响应的实际可见内容不完全对应。例如，即使是空字符串响应，output_tokens 也会是非零值。

错误响应

当请求出现问题时，API 将返回一个错误响应对象，HTTP 状态码在 4XX-5XX 范围内。

常见错误状态码

错误响应示例:

{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid API key provided",
    "code": "invalid_api_key"
  }
}

主要错误类型:

Deepseek reasoning 对话格式（Reasoning Content）

官方文档

📝 简介

Deepseek-reasoner 是 DeepSeek 推出的推理模型。在输出最终回答之前，模型会先输出一段思维链内容，以提升最终答案的准确性。API 向用户开放 deepseek-reasoner 思维链的内容，以供用户查看、展示、蒸馏使用。

💡 请求示例

基础文本对话 ✅

curl https://$Burncloud_API_BaseUrl/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $Burncloud_API_KEY" \
  -d '{
    "model": "deepseek-reasoner",
    "messages": [
      {
        "role": "user",
        "content": "9.11 and 9.8, which is greater?"
      }
    ],
    "max_tokens": 4096
  }'

响应示例:

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "deepseek-reasoner",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "reasoning_content": "让我一步步思考:\n1. 我们需要比较9.11和9.8的大小\n2. 两个数都是小数,我们可以直接比较\n3. 9.8 = 9.80\n4. 9.11 < 9.80\n5. 所以9.8更大",
      "content": "9.8 is greater than 9.11."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 15,
    "total_tokens": 25
  }
}

流式响应 ✅

curl https://$Burncloud_API_BaseUrl/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $Burncloud_API_KEY" \
  -d '{
    "model": "deepseek-reasoner",
    "messages": [
      {
        "role": "user",
        "content": "9.11 and 9.8, which is greater?"
      }
    ],
    "stream": true
  }'

流式响应示例:

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"deepseek-reasoner","choices":[{"index":0,"delta":{"role":"assistant","reasoning_content":"让我"},"finish_reason":null}]}

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"deepseek-reasoner","choices":[{"index":0,"delta":{"reasoning_content":"一步步"},"finish_reason":null}]}

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"deepseek-reasoner","choices":[{"index":0,"delta":{"reasoning_content":"思考:"},"finish_reason":null}]}

// ... 更多思维链内容 ...

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"deepseek-reasoner","choices":[{"index":0,"delta":{"content":"9.8"},"finish_reason":null}]}

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"deepseek-reasoner","choices":[{"index":0,"delta":{"content":" is greater"},"finish_reason":null}]}

// ... 更多最终答案内容 ...

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"deepseek-reasoner","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

📮 请求

端点

POST /v1/chat/completions

鉴权方法

在请求头中包含以下内容进行 API 密钥认证：

Authorization: Bearer $Burncloud_API_KEY

其中 $DEEPSEEK_API_KEY 是您的 API 密钥。

请求体参数

messages

到目前为止包含对话的消息列表。请注意,如果您在输入的 messages 序列中传入了 reasoning_content，API 会返回 400 错误。

model

要使用的模型 ID。目前仅支持 deepseek-reasoner。

max_tokens

最终回答的最大长度（不含思维链输出）。请注意，思维链的输出最多可以达到 32K tokens。

stream

是否使用流式响应。

不支持的参数

以下参数当前不支持:

注意:为了兼容已有软件,设置 temperature、top_p、presence_penalty、frequency_penalty 参数不会报错,但也不会生效。设置 logprobs、top_logprobs 会报错。

支持的功能

不支持的功能

📥 响应

成功响应

返回一个聊天补全对象，如果请求被流式传输，则返回聊天补全块对象的流式序列。

id

object

created

model

choices

usage

📝 上下文拼接说明

在每一轮对话过程中，模型会输出思维链内容（reasoning_content）和最终回答（content）。在下一轮对话中，之前轮输出的思维链内容不会被拼接到上下文中，如下图所示：

Deepseek reasoning 上下文拼接示意图

!!! warning "注意" 如果您在输入的 messages 序列中，传入了reasoning_content，API 会返回 400 错误。因此，请删除 API 响应中的 reasoning_content 字段，再发起 API 请求，方法如下方使用示例所示。

使用示例:

from openai import OpenAI
client = OpenAI(api_key="<DeepSeek API Key>", base_url="https://$Burncloud_API_BaseUrl")

# 第一轮对话
messages = [{"role": "user", "content": "9.11 and 9.8, which is greater?"}]
response = client.chat.completions.create(
    model="deepseek-reasoner",
    messages=messages
)

reasoning_content = response.choices[0].message.reasoning_content
content = response.choices[0].message.content

# 第二轮对话 - 只拼接最终回答content
messages.append({'role': 'assistant', 'content': content})
messages.append({'role': 'user', 'content': "How many Rs are there in the word 'strawberry'?"})
response = client.chat.completions.create(
    model="deepseek-reasoner", 
    messages=messages
)

流式响应示例:

# 第一轮对话
messages = [{"role": "user", "content": "9.11 and 9.8, which is greater?"}]
response = client.chat.completions.create(
    model="deepseek-reasoner",
    messages=messages,
    stream=True
)

reasoning_content = ""
content = ""

for chunk in response:
    if chunk.choices[0].delta.reasoning_content:
        reasoning_content += chunk.choices[0].delta.reasoning_content
    else:
        content += chunk.choices[0].delta.content

# 第二轮对话 - 只拼接最终回答content
messages.append({"role": "assistant", "content": content})
messages.append({'role': 'user', 'content': "How many Rs are there in the word 'strawberry'?"})
response = client.chat.completions.create(
    model="deepseek-reasoner",
    messages=messages,
    stream=True
)

Google Gemini 对话格式（Generate Content）

官方文档

📝 简介

Google Gemini API 支持使用图片、音频、代码、工具等生成内容。给定输入 GenerateContentRequest 生成模型响应。支持文本生成、视觉理解、音频处理、长上下文、代码执行、JSON 模式、函数调用等多种功能。

💡 请求示例

基础文本对话 ✅

curl "https://$Burncloud_API_BaseUrl/v1beta/models/gemini-2.0-flash:generateContent?key=$Burncloud_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[{"text": "Write a story about a magic backpack."}]
        }]
       }' 2> /dev/null

图像分析对话 ✅

# 使用临时文件保存base64编码的图片数据
TEMP_B64=$(mktemp)
trap 'rm -f "$TEMP_B64"' EXIT
base64 $B64FLAGS $IMG_PATH > "$TEMP_B64"

# 使用临时文件保存JSON载荷
TEMP_JSON=$(mktemp)
trap 'rm -f "$TEMP_JSON"' EXIT

cat > "$TEMP_JSON" << EOF
{
  "contents": [{
    "parts":[
      {"text": "Tell me about this instrument"},
      {
        "inline_data": {
          "mime_type":"image/jpeg",
          "data": "$(cat "$TEMP_B64")"
        }
      }
    ]
  }]
}
EOF

curl "https://$Burncloud_API_BaseUrl/v1beta/models/gemini-2.0-flash:generateContent?key=$Burncloud_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d "@$TEMP_JSON" 2> /dev/null

函数调用 ✅

cat > tools.json << EOF
{
  "function_declarations": [
    {
      "name": "enable_lights",
      "description": "Turn on the lighting system."
    },
    {
      "name": "set_light_color",
      "description": "Set the light color. Lights must be enabled for this to work.",
      "parameters": {
        "type": "object",
        "properties": {
          "rgb_hex": {
            "type": "string",
            "description": "The light color as a 6-digit hex string, e.g. ff0000 for red."
          }
        },
        "required": [
          "rgb_hex"
        ]
      }
    },
    {
      "name": "stop_lights",
      "description": "Turn off the lighting system."
    }
  ]
} 
EOF

curl "https://$Burncloud_API_BaseUrl/v1beta/models/gemini-2.0-flash:generateContent?key=$Burncloud_API_KEY" \
  -H 'Content-Type: application/json' \
  -d @<(echo '
  {
    "system_instruction": {
      "parts": {
        "text": "You are a helpful lighting system bot. You can turn lights on and off, and you can set the color. Do not perform any other tasks."
      }
    },
    "tools": ['$(cat tools.json)'],

    "tool_config": {
      "function_calling_config": {"mode": "auto"}
    },

    "contents": {
      "role": "user",
      "parts": {
        "text": "Turn on the lights please."
      }
    }
  }
') 2>/dev/null |sed -n '/"content"/,/"finishReason"/p'

JSON 模式响应 ✅

curl "https://$Burncloud_API_BaseUrl/v1beta/models/gemini-2.0-flash:generateContent?key=$Burncloud_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
    "contents": [{
      "parts":[
        {"text": "List 5 popular cookie recipes"}
        ]
    }],
    "generationConfig": {
        "response_mime_type": "application/json",
        "response_schema": {
          "type": "ARRAY",
          "items": {
            "type": "OBJECT",
            "properties": {
              "recipe_name": {"type":"STRING"},
            }
          }
        }
    }
}' 2> /dev/null | head

音频处理 🟡

!!! warning "文件上传限制" 仅支持通过 inline_data 以 base64 方式上传音频，不支持 file_data.file_uri 或 File API。

# 使用File API上传音频数据到API请求
# 使用 base64 inline_data 上传音频数据到 API 请求
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi
AUDIO_B64=$(base64 $B64FLAGS "$AUDIO_PATH")

curl "https://$Burncloud_API_BaseUrl/v1beta/models/gemini-2.0-flash:generateContent?key=$Burncloud_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [
        {"text": "Please describe this audio file."},
        {"inline_data": {"mime_type": "audio/mpeg", "data": "'$AUDIO_B64'"}}
      ]
    }]
  }' 2> /dev/null | jq ".candidates[].content.parts[].text"

视频处理 🟡

!!! warning "文件上传限制" 仅支持通过 inline_data 以 base64 方式上传视频，不支持 file_data.file_uri 或 File API。

# 使用File API上传视频数据到API请求
# 使用 base64 inline_data 上传视频数据到 API 请求
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi
VIDEO_B64=$(base64 $B64FLAGS "$VIDEO_PATH")

curl "https://$Burncloud_API_BaseUrl/v1beta/models/gemini-2.0-flash:generateContent?key=$Burncloud_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [
        {"text": "Transcribe the audio from this video and provide visual descriptions."},
        {"inline_data": {"mime_type": "video/mp4", "data": "'$VIDEO_B64'"}}
      ]
    }]
  }' 2> /dev/null | jq ".candidates[].content.parts[].text"

PDF处理 🟡

!!! warning "文件上传限制" 仅支持通过 inline_data 以 base64 方式上传 PDF，不支持 file_data.file_uri 或 File API。

MIME_TYPE=$(file -b --mime-type "${PDF_PATH}")
# 使用 base64 inline_data 上传 PDF 文件到 API 请求
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi
PDF_B64=$(base64 $B64FLAGS "$PDF_PATH")

echo $MIME_TYPE

curl "https://$Burncloud_API_BaseUrl/v1beta/models/gemini-2.0-flash:generateContent?key=$Burncloud_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [
        {"text": "Can you add a few more lines to this poem?"},
        {"inline_data": {"mime_type": "application/pdf", "data": "'$PDF_B64'"}}
      ]
    }]
  }' 2> /dev/null | jq ".candidates[].content.parts[].text"

聊天对话 ✅

curl https://$Burncloud_API_BaseUrl/v1beta/models/gemini-2.0-flash:generateContent?key=$Burncloud_API_KEY \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [
        {"role":"user",
         "parts":[{
           "text": "Hello"}]},
        {"role": "model",
         "parts":[{
           "text": "Great to meet you. What would you like to know?"}]},
        {"role":"user",
         "parts":[{
           "text": "I have two dogs in my house. How many paws are in my house?"}]},
      ]
    }' 2> /dev/null | grep "text"

流式响应 ✅

curl "https://$Burncloud_API_BaseUrl/v1beta/models/gemini-2.0-flash:streamGenerateContent?alt=sse&key=$Burncloud_API_KEY" \
    -H 'Content-Type: application/json' \
    --no-buffer \
    -d '{
      "contents": [{
        "parts": [{"text": "写一个关于魔法背包的故事"}]
      }]
    }'

代码执行 ✅

curl "https://$Burncloud_API_BaseUrl/v1beta/models/gemini-2.0-flash:generateContent?key=$Burncloud_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts": [{"text": "计算斐波那契数列的第10项"}]
      }],
      "tools": [{
        "codeExecution": {}
      }]
    }'

生成配置 ✅

curl https://$Burncloud_API_BaseUrl/v1beta/models/gemini-2.0-flash:generateContent?key=$Burncloud_API_KEY \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
        "contents": [{
            "parts":[
                {"text": "Explain how AI works"}
            ]
        }],
        "generationConfig": {
            "stopSequences": [
                "Title"
            ],
            "temperature": 1.0,
            "maxOutputTokens": 800,
            "topP": 0.8,
            "topK": 10
        }
    }'  2> /dev/null | grep "text"

安全设置 ✅

echo '{
    "safetySettings": [
        {"category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_ONLY_HIGH"},
        {"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_MEDIUM_AND_ABOVE"}
    ],
    "contents": [{
        "parts":[{
            "text": "'I support Martians Soccer Club and I think Jupiterians Football Club sucks! Write a ironic phrase about them.'"}]}]}' > request.json

curl "https://$Burncloud_API_BaseUrl/v1beta/models/gemini-2.0-flash:generateContent?key=$Burncloud_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d @request.json 2> /dev/null

系统指令 ✅

curl "https://$Burncloud_API_BaseUrl/v1beta/models/gemini-2.0-flash:generateContent?key=$Burncloud_API_KEY" \
-H 'Content-Type: application/json' \
-d '{ "system_instruction": {
    "parts":
      { "text": "You are a cat. Your name is Neko."}},
    "contents": {
      "parts": {
        "text": "Hello there"}}}'

📮 请求

端点

生成内容

POST https://$Burncloud_API_BaseUrl/v1beta/{model=models/*}:generateContent

流式生成内容

POST https://$Burncloud_API_BaseUrl/v1beta/{model=models/*}:streamGenerateContent

鉴权方法

在请求URL参数中包含API密钥：

?key=$Burncloud_API_KEY

其中 $Burncloud_API_KEY 是您的 Google AI API 密钥。

路径参数

model

用于生成补全项的模型名称。

格式：models/{model}，例如 models/gemini-2.0-flash

请求体参数

contents

与模型当前对话的内容。对于单轮查询，这是单个实例。对于聊天等多轮查询，这是包含对话历史记录和最新请求的重复字段。

Content 对象属性：

属性 类型 必需 描述
parts 数组 是 有序的内容部分，构成单个消息
role 字符串 否 对话中内容的生产者。user、model、function 或 tool

Part 对象属性：

属性 类型 必需 描述
text 字符串 否 纯文本内容
inlineData 对象 否 内联媒体字节数据
fileData 对象 否 上传文件的URI引用
functionCall 对象 否 函数调用请求
functionResponse 对象 否 函数调用响应
executableCode 对象 否 可执行代码
codeExecutionResult 对象 否 代码执行结果

InlineData 对象属性：

属性 类型 必需 描述
mimeType 字符串 是 媒体的MIME类型
data 字符串 是 base64编码的媒体数据

FileData 对象属性：

属性 类型 必需 描述
mimeType 字符串 是 文件的MIME类型
fileUri 字符串 是 文件的URI

tools

模型可能用于生成下一个响应的工具列表。支持的工具包括函数和代码执行。

Tool 对象属性：

属性 类型 必需 描述
functionDeclarations 数组 否 可选的函数声明列表
codeExecution 对象 否 启用模型执行代码

FunctionDeclaration 对象属性：

属性 类型 必需 描述
name 字符串 是 函数名称
description 字符串 否 函数功能描述
parameters 对象 否 函数参数，JSON Schema格式

FunctionCall 对象属性：

属性 类型 必需 描述
name 字符串 是 要调用的函数名称
args 对象 否 函数参数的键值对

FunctionResponse 对象属性：

属性 类型 必需 描述
name 字符串 是 调用的函数名称
response 对象 是 函数调用的响应数据

ExecutableCode 对象属性：

属性 类型 必需 描述
language 枚举 是 代码的编程语言
code 字符串 是 要执行的代码

CodeExecutionResult 对象属性：

属性 类型 必需 描述
outcome 枚举 是 代码执行的结果状态
output 字符串 否 代码执行的输出内容

CodeExecution 对象属性：

属性 类型 必需 描述
{} 空对象 - 启用代码执行功能的空配置对象

toolConfig

请求中指定的任何工具的工具配置。

ToolConfig 对象属性：

属性 类型 必需 描述
functionCallingConfig 对象 否 函数调用配置

FunctionCallingConfig 对象属性：

属性 类型 必需 描述
mode 枚举 否 指定函数调用的模式
allowedFunctionNames 数组 否 允许调用的函数名列表

FunctionCallingMode 枚举值：

safetySettings

用于屏蔽不安全内容的 SafetySetting 实例列表。

SafetySetting 对象属性：

属性 类型 必需 描述
category 枚举 是 安全类别
threshold 枚举 是 屏蔽阈值

HarmCategory 枚举值：

HarmBlockThreshold 枚举值：

HarmBlockThreshold 完整枚举值：

systemInstruction

开发者设置的系统指令。目前仅支持文本。

generationConfig

模型生成和输出的配置选项。

GenerationConfig 对象属性：

属性 类型 必需 描述
stopSequences 数组 否 用于停止生成输出的字符序列集（最多5个）
responseMimeType 字符串 否 生成的候选文本的MIME类型
responseSchema 对象 否 生成的候选文本的输出架构
responseModalities 数组 否 请求的响应模式
candidateCount 整数 否 要返回的生成的回答数量
maxOutputTokens 整数 否 候选回答中包含的令牌数量上限
temperature 数字 否 控制输出的随机性，范围[0.0, 2.0]
topP 数字 否 在抽样时要考虑的令牌的累计概率上限
topK 整数 否 抽样时要考虑的令牌数量上限
seed 整数 否 解码中使用的种子
presencePenalty 数字 否 存在性惩罚
frequencyPenalty 数字 否 频率惩罚
responseLogprobs 布尔值 否 是否在响应中导出logprobs结果
logprobs 整数 否 返回的顶部logprob的数量
enableEnhancedCivicAnswers 布尔值 否 启用增强型城市服务回答
speechConfig 对象 否 语音生成配置
thinkingConfig 对象 否 思考功能的配置
mediaResolution 枚举 否 指定的媒体分辨率

支持的 MIME 类型：

Modality 枚举值：

Schema 对象属性：

属性 类型 必需 描述
type 枚举 是 数据类型
description 字符串 否 字段描述
enum 数组 否 枚举值列表（当type为string时）
example 任意类型 否 示例值
nullable 布尔值 否 是否可为null
format 字符串 否 字符串格式（如date、date-time等）
items 对象 否 数组项的Schema（当type为array时）
properties 对象 否 对象属性的Schema映射（当type为object时）
required 数组 否 必需属性的名称列表
minimum 数字 否 数字的最小值
maximum 数字 否 数字的最大值
minItems 整数 否 数组的最小长度
maxItems 整数 否 数组的最大长度
minLength 整数 否 字符串的最小长度
maxLength 整数 否 字符串的最大长度

Type 枚举值：

支持的编程语言（ExecutableCode）：

代码执行结果枚举（Outcome）：

cachedContent

缓存的内容的名称，用于用作提供预测的上下文。格式：cachedContents/{cachedContent}

📥 响应

GenerateContentResponse

支持多个候选回答的模型的回答。系统会针对提示以及每个候选项报告安全分级和内容过滤。

candidates

Candidate 对象属性：

属性 类型 描述
content 对象 模型返回的生成内容
finishReason 枚举 模型停止生成词元的原因
safetyRatings 数组 候选回答安全性的评分列表
citationMetadata 对象 模型生成的候选项的引用信息
tokenCount 整数 此候选项的令牌数
groundingAttributions 数组 为生成有依据的回答所参考的来源提供方信息
groundingMetadata 对象 候选对象的参考元数据
avgLogprobs 数字 候选项的平均对数概率得分
logprobsResult 对象 回答令牌和前置令牌的对数似然度得分
urlRetrievalMetadata 对象 与网址情境检索工具相关的元数据
urlContextMetadata 对象 与网址情境检索工具相关的元数据
index 整数 响应候选列表中候选项的索引

FinishReason 枚举值：

promptFeedback

PromptFeedback 对象属性：

属性 类型 描述
blockReason 枚举 屏蔽该提示的原因
safetyRatings 数组 问题安全性的评分

BlockReason 枚举值：

usageMetadata

UsageMetadata 对象属性：

属性 类型 描述
promptTokenCount 整数 提示中的词元数
cachedContentTokenCount 整数 提示的缓存部分中的词元数
candidatesTokenCount 整数 所有生成的候选回答中的词元总数
totalTokenCount 整数 生成请求的总令牌数
toolUsePromptTokenCount 整数 工具使用提示中的词元数量
thoughtsTokenCount 整数 思考模型的想法token数
promptTokensDetails 数组 在请求输入中处理的模态列表
candidatesTokensDetails 数组 响应中返回的模态列表
cacheTokensDetails 数组 请求输入中缓存内容的模态列表
toolUsePromptTokensDetails 数组 为工具使用请求输入处理的模态列表

modelVersion

responseId

完整响应示例

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "你好！我是 Gemini，一个由 Google 开发的人工智能助手。我可以帮助您解答问题、提供信息、协助写作、代码编程等多种任务。请告诉我有什么可以为您效劳的！"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE",
          "blocked": false
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH", 
          "probability": "NEGLIGIBLE",
          "blocked": false
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE",
          "blocked": false
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE",
          "blocked": false
        }
      ],
      "tokenCount": 47
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "probability": "NEGLIGIBLE"
      }
    ]
  },
  "usageMetadata": {
    "promptTokenCount": 4,
    "candidatesTokenCount": 47,
    "totalTokenCount": 51,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 4
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "TEXT", 
        "tokenCount": 47
      }
    ]
  },
  "modelVersion": "gemini-2.0-flash",
  "responseId": "response-12345"
}

🔧 高级功能

安全评级

SafetyRating 对象属性：

属性 类型 描述
category 枚举 此评分的类别
probability 枚举 此内容的有害概率
blocked 布尔值 此内容是否因此分级而被屏蔽

HarmProbability 枚举值：

引用元数据

CitationMetadata 对象属性：

属性 类型 描述
citationSources 数组 特定回复的来源引用

CitationSource 对象属性：

属性 类型 描述
startIndex 整数 归因于此来源的响应片段的开始索引
endIndex 整数 归因细分的结束索引（不含）
uri 字符串 被归因为文本部分来源的URI
license 字符串 被归因为片段来源的GitHub项目的许可

代码执行

当启用代码执行工具时，模型可以生成和执行代码来解决问题。

代码执行示例响应：

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "我来计算斐波那契数列的第10项："
          },
          {
            "executableCode": {
              "language": "PYTHON",
              "code": "def fibonacci(n):\n    if n <= 1:\n        return n\n    else:\n        return fibonacci(n-1) + fibonacci(n-2)\n\nresult = fibonacci(10)\nprint(f'第10项斐波那契数是: {result}')"
            }
          },
          {
            "codeExecutionResult": {
              "outcome": "OK",
              "output": "第10项斐波那契数是: 55"
            }
          },
          {
            "text": "所以斐波那契数列的第10项是55。"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ]
}

接地功能 (Grounding)

GroundingMetadata 对象属性：

属性 类型 描述
groundingChunks 数组 从指定的接地源检索到的支持参考文献列表
groundingSupports 数组 接地支持列表
webSearchQueries 数组 用于后续网页搜索的网页搜索查询
searchEntryPoint 对象 后续网页搜索的Google搜索条目
retrievalMetadata 对象 与基准流程中检索相关的元数据

GroundingAttribution 对象属性：

属性 类型 描述
sourceId 对象 对此归因做出贡献的来源的标识符
content 对象 构成此归因的来源内容

AttributionSourceId 对象属性：

属性 类型 描述
groundingPassage 对象 内嵌段落的标识符
semanticRetrieverChunk 对象 通过Semantic Retriever提取的Chunk的标识符

GroundingPassageId 对象属性：

属性 类型 描述
passageId 字符串 与GenerateAnswerRequest的GroundingPassage.id匹配的段落的ID
partIndex 整数 GenerateAnswerRequest的GroundingPassage.content中的部分的索引

SemanticRetrieverChunk 对象属性：

属性 类型 描述
source 字符串 与请求的SemanticRetrieverConfig.source匹配的来源名称
chunk 字符串 包含归因文本的Chunk的名称

SearchEntryPoint 对象属性：

属性 类型 描述
renderedContent 字符串 可嵌入网页或应用WebView中的Web内容代码段
sdkBlob 字符串 使用base64编码的JSON，表示搜索词和搜索URL元组的数组

Segment 对象属性：

属性 类型 描述
partIndex 整数 Part对象在其父级Content对象中的索引
startIndex 整数 给定part中的起始索引，以字节为单位
endIndex 整数 给定分块中的结束索引，以字节为单位
text 字符串 与响应中的片段对应的文本

RetrievalMetadata 对象属性：

属性 类型 描述
googleSearchDynamicRetrievalScore 数字 Google搜索中的信息有助于回答问题的概率得分，范围[0,1]

GroundingChunk 对象属性：

属性 类型 描述
web 对象 来自网络的接地分块

Web 对象属性：

属性 类型 描述
uri 字符串 分块的URI引用
title 字符串 数据块的标题

GroundingSupport 对象属性：

属性 类型 描述
groundingChunkIndices 数组 索引列表，用于指定与版权主张相关的引文
confidenceScores 数组 支持参考文档的置信度分数，范围为0到1
segment 对象 此支持请求所属的内容片段

多模态处理

Gemini API 支持处理多种模态的输入和输出：

支持的输入模态：

ModalityTokenCount 对象属性：

属性 类型 描述
modality 枚举 与此令牌数关联的模态
tokenCount 整数 令牌数量

MediaResolution 枚举值：

思考功能

ThinkingConfig 对象属性：

属性 类型 描述
includeThoughts 布尔值 是否要在回答中包含思考内容
thinkingBudget 整数 模型应生成的想法token的数量

语音生成

SpeechConfig 对象属性：

属性 类型 描述
voiceConfig 对象 单声音输出的配置
multiSpeakerVoiceConfig 对象 多音箱设置的配置
languageCode 字符串 用于语音合成的语言代码

VoiceConfig 对象属性：

属性 类型 描述
prebuiltVoiceConfig 对象 要使用的预构建语音的配置

PrebuiltVoiceConfig 对象属性：

属性 类型 描述
voiceName 字符串 要使用的预设语音的名称

MultiSpeakerVoiceConfig 对象属性：

属性 类型 描述
speakerVoiceConfigs 数组 所有已启用的音箱语音

SpeakerVoiceConfig 对象属性：

属性 类型 描述
speaker 字符串 要使用的音箱的名称
voiceConfig 对象 要使用的语音的配置

支持的语言代码：

Logprobs 结果

LogprobsResult 对象属性：

属性 类型 描述
topCandidates 数组 长度等于解码步骤总数
chosenCandidates 数组 长度等于解码步骤总数，所选候选项不一定在topCandidates中

TopCandidates 对象属性：

属性 类型 描述
candidates 数组 按对数概率降序排序的候选项

Candidate (Logprobs) 对象属性：

属性 类型 描述
token 字符串 候选项的令牌字符串值
tokenId 整数 候选项的令牌ID值
logProbability 数字 候选项的对数概率

URL检索功能

UrlRetrievalMetadata 对象属性：

属性 类型 描述
urlRetrievalContexts 数组 网址检索情境列表

UrlRetrievalContext 对象属性：

属性 类型 描述
retrievedUrl 字符串 工具检索到的网址

UrlContextMetadata 对象属性：

属性 类型 描述
urlMetadata 数组 网址上下文列表

UrlMetadata 对象属性：

属性 类型 描述
retrievedUrl 字符串 工具检索到的网址
urlRetrievalStatus 枚举 网址检索的状态

UrlRetrievalStatus 枚举值：

完整安全类别

HarmCategory 完整枚举值：

HarmProbability 完整枚举值：

Modality 完整枚举值：

MediaResolution 完整枚举值：

UrlRetrievalStatus 完整枚举值：

🔍 错误处理

常见错误码

错误码 描述
400 请求格式错误或参数无效
401 API密钥无效或缺失
403 权限不足或配额限制
429 请求频率过高
500 服务器内部错误

详细错误码说明

错误码 状态 描述 解决方案
400 INVALID_ARGUMENT 请求参数无效或格式错误 检查请求参数格式和必需字段
400 FAILED_PRECONDITION 请求的前置条件不满足 确保满足API调用的前置条件
401 UNAUTHENTICATED API密钥无效、缺失或已过期 检查API密钥的有效性和格式
403 PERMISSION_DENIED 权限不足或配额已用完 检查API密钥权限或升级配额
404 NOT_FOUND 指定的模型或资源不存在 验证模型名称和资源路径
413 PAYLOAD_TOO_LARGE 请求体太大 减少输入内容大小或分批处理
429 RESOURCE_EXHAUSTED 请求频率超限或配额不足 降低请求频率或等待配额重置
500 INTERNAL 服务器内部错误 重试请求，如持续出现联系支持
503 UNAVAILABLE 服务暂时不可用 等待一段时间后重试
504 DEADLINE_EXCEEDED 请求超时 减少输入大小或重试请求

错误响应示例

{
  "error": {
    "code": 400,
    "message": "Invalid argument: contents",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "contents",
            "description": "contents is required"
          }
        ]
      }
    ]
  }
}