# 大语言模型 API 接口文档 AI Relay Station: Unified API Development Guide for Large Language Models # 快速接入BurnCloud API（必看） 本文涉及到接入Burncloud API用到的两个关键变量，接入端点 **$Burncloud\_API\_BaseUrl** 和密钥 **$Burncloud\_API\_KEY** ，请务必花1分钟过一眼，看看如何获取。 1. Burncloud的API服务分标准服务C端和企业服务B端，接入前请先确认账号所在的端点（教程中的 **$Burncloud\_API\_BaseUrl** 的值）,教程将以标准服务C端接入点举例。 - 标准服务C端接入点：https://ai.burncloud.com - 企业服务B端接入点：https://b.burncloud.com 2. [创建账户并登录](http://ai.burncloud.com/register) 1.1 [创建账户](http://ai.burncloud.com/register) 1.2 [登录](http://ai.burncloud.com/login) 3. [创建您的API密钥](http://ai.burncloud.com/token) ，教程中的 **$Burncloud\_API\_KEY** 的值。 - 来到创建Token的页面 [![创建令牌步骤1](https://docs.burncloud.com/uploads/images/gallery/2025-08/scaled-1680-/2025-08-27-133808-530.png)](https://docs.burncloud.com/uploads/images/gallery/2025-08/2025-08-27-133808-530.png) - 创建Token，填写token名称==》选择token将调用的模型所在的分组==》开启无限额度（可选）==》提交 [![创建令牌步骤2](https://docs.burncloud.com/uploads/images/gallery/2025-08/scaled-1680-/2025-08-27-134409-894.png)](https://docs.burncloud.com/uploads/images/gallery/2025-08/2025-08-27-134409-894.png) - 拷贝token去使用 [![创建令牌步骤3](https://docs.burncloud.com/uploads/images/gallery/2025-08/scaled-1680-/2025-08-27-134523-969.png)](https://docs.burncloud.com/uploads/images/gallery/2025-08/2025-08-27-134523-969.png) 4. 在API调用中使用您的密钥。例如： ``` https://ai.burncloud.com/v1/chat/completions Token: sk-6B72ZIOj0p0tKEyaoyVAgRAz6SMtfxxxxxxxx curl https://ai.burncloud.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-6B72ZIOj0p0tKEyaoyVAgRAz6SMtfxxxxxxxx" \ -d '{ "model": "deepseek-r1", "messages": [{ "role": "user", "content": "你好，你今天怎么样？" }], "temperature": 0.7, "max_tokens": 150 }' ``` 5. [为您的账户充值](http://ai.burncloud.com/topup) 开始使用API服务 # 聊天 Chat # OpenAI 对话格式 （Chat Completions） 官方文档 - [OpenAI Chat](https://platform.openai.com/docs/api-reference/chat) ## 📝 简介 给定一组包含对话的消息列表，模型将返回一个响应。相关指南可参阅OpenAI官网：[Chat Completions](https://platform.openai.com/docs/guides/chat) ## 💡 请求示例 ### 基础文本对话 ✅ ```bash 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": "你好！" } ] }' ``` **响应示例:** ```json { "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" } ``` ### 图像分析对话 ✅ ```bash 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 }' ``` **响应示例:** ```json { "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" } ``` ### 流式响应 ✅ ```bash 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 }' ``` **流式响应示例:** ```jsonl {"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"}]} ``` ### 函数调用 ✅ ```bash 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" }' ``` **响应示例:** ```json { "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 请求 ✅ ```bash 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 }' ``` **响应示例:** ```json { "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` - 类型：布尔值或 null - 必需：否 - 默认值：false 是否存储此聊天补全请求的输出以用于我们的模型蒸馏或评估产品。 #### `reasoning_effort` - 类型：字符串或 null - 必需：否 - 默认值：medium - 仅适用于 o系列 的模型 约束推理模型的推理工作。当前支持的值为 `low`、`medium` 和 `high`。减少推理工作可以加快响应速度并减少响应中用于推理的标记数。 #### `metadata` - 类型：map - 必需：否 可以附加到对象的16个键值对集合。这对于以结构化格式存储对象的其他信息很有用,并可以通过 API 或仪表板查询对象。 键是最大长度为64个字符的字符串。值是最大长度为512个字符的字符串。 #### `modalities` - 类型：数组或 null - 必需：否 您希望模型为此请求生成的输出类型。大多数模型都能生成文本,这是默认设置: ["text"] 该模型还可以用于生成音频。要请求此模型同时生成文本和音频响应,您可以使用: ["text", "audio"] #### `prediction` - 类型：对象 - 必需：否 预测输出的配置,当提前知道模型响应的大部分内容时,可以大大提高响应时间。这在您只对文件进行微小更改时最常见。 **可能的类型：** | 类型 | 描述 | |------|------| | **静态内容** | 静态预测输出内容，例如正在重新生成的具有微小更改的文本文件内容。 | **静态内容属性：** | 属性 | 类型 | 必需 | 描述 | |------|------|------|------| | `content` | 字符串或数组 | 是 | 生成模型响应时应匹配的内容。如果生成的标记与此内容匹配，则整个模型响应可以更快地返回。 | | `type` | 字符串 | 是 | 要提供的预测内容类型。当前类型始终为 `content`。 | **内容可能的类型：** 1. **文本内容（字符串）** - 用于预测输出的内容。这通常是您正在重新生成的文件的文本，只有微小更改。 2. **内容部分数组（数组）** - 具有定义类型的内容部分数组。支持的选项因用于生成响应的模型而异。可以包含文本输入。 **内容部分数组属性：** | 属性 | 类型 | 必需 | 描述 | |------|------|------|------| | `text` | 字符串 | 是 | 文本内容。 | | `type` | 字符串 | 是 | 内容部分的类型。 | #### `audio` - 类型：对象或 null - 必需：否 音频输出的参数。当使用 `modalities: ["audio"]` 请求音频输出时需要。 | 属性 | 类型 | 必需 | 描述 | |------|------|------|------| | `format` | 字符串 | 是 | 指定输出音频格式。必须是以下之一：wav、mp3、flac、opus 或 pcm16。 | | `voice` | 字符串 | 是 | 模型用于响应的声音。支持的声音包括：alloy、ash、ballad、coral、echo、fable、nova、onyx、sage 和 shimmer。 | #### `temperature` - 类型：数字或 null - 必需：否 - 默认值：1 要使用的采样温度，介于 0 和 2 之间。较高的值（如0.8）会使输出更加随机，而较低的值（如0.2）会使其更加集中和确定性。我们通常建议更改此值或 `top_p`，但不要同时更改。 #### `top_p` - 类型：数字或 null - 必需：否 - 默认值：1 一种替代采样温度的方法，称为核采样，其中模型考虑具有 top_p 概率质量的标记结果。因此，0.1 意味着只考虑包含前 10% 概率质量的标记。 我们通常建议更改此值或 `temperature`，但不要同时更改。 #### `n` - 类型：整数或 null - 必需：否 - 默认值：1 为每个输入消息生成多少个聊天补全选择。请注意，您将根据所有选择生成的标记数量收费。保持 `n` 为 1 可最大限度地降低成本。 #### `stop` - 类型：字符串/数组/null - 必需：否 - 默认值：null - 不支持最新的推理模型和 .o3、o4-mini API 将停止生成更多标记的最多 4 个序列。返回的文本不会包含停止序列。 #### `max_tokens` - 类型：整数或 null - 必需：否 聊天补全中可以生成的最大标记数。此值可用于控制通过 API 生成的文本成本。 该值现已弃用，取而代之的是 `max_completion_tokens`，并且与 `o1` 系列模型不兼容。 #### `max_completion_tokens` - 类型：整数或 null - 必需：否 补全中可以生成的标记数的上限，包括可见输出标记和推理标记。 #### `presence_penalty` - 类型：数字或 null - 必需：否 - 默认值：0 介于 -2.0 和 2.0 之间的数字。正值根据新标记到目前为止在文本中出现的情况来惩罚它们，从而增加模型讨论新主题的可能性。 #### `frequency_penalty` - 类型：数字或 null - 必需：否 - 默认值：0 介于 -2.0 和 2.0 之间的数字。正值根据新标记到目前为止在文本中的现有频率来惩罚它们，从而降低模型逐字重复同一行的可能性。 #### `logit_bias` - 类型：map - 必需：否 - 默认值：null 修改指定标记出现在补全中的可能性。 接受一个 JSON 对象，该对象将标记（由分词器中的标记 ID 指定）映射到从 -100 到 100 的关联偏差值。在数学上，偏差被添加到模型在采样之前生成的对数中。确切的效果会因模型而异，但介于 -1 和 1 之间的值应该会减少或增加选择的可能性；像 -100 或 100 这样的值应该导致相关标记被禁止或独占选择。 #### `logprobs` - 类型：布尔值或 null - 必需：否 - 默认值：false 是否返回输出标记的对数概率。如果为 true，则返回 `message.content` 中每个输出标记的对数概率。 #### `user` - 类型：字符串 - 必需：否 表示最终用户的唯一标识符，可以帮助 OpenAI 监控和检测滥用行为。[了解更多](https://platform.openai.com/docs/guides/safety-best-practices/end-user-ids)。 #### `service_tier` - 类型：字符串或 null - 必需：否 - 默认值：auto 指定用于处理请求的延迟层级。此参数与订阅了 scale tier 服务的客户相关： - 如果设置为 'auto'，且项目启用了 Scale tier，系统将使用 scale tier 信用直到用完 - 如果设置为 'auto'，且项目未启用 Scale tier，请求将使用默认服务层级处理，具有较低的正常运行时间 SLA 且无延迟保证 - 如果设置为 'default'，请求将使用默认服务层级处理，具有较低的正常运行时间 SLA 且无延迟保证 - 如果设置为 'flex'，请求将使用 Flex Processing 服务层级处理。详情请参阅文档。 - 未设置时，默认行为为 'auto' - 当设置此参数时，响应体将包含使用的 service_tier #### `stream_options` - 类型：对象或 null - 必需：否 - 默认值：null 流式响应的选项。仅在设置 `stream: true` 时使用。 **可能的属性：** | 属性 | 类型 | 必需 | 描述 | |------|------|------|------| | `include_usage` | 布尔值 | 否 | 如果设置，将在 data: [DONE] 消息之前流式传输一个附加块。该块上的 usage 字段显示整个请求的令牌使用统计信息，choices 字段始终为空数组。所有其他块也将包含 usage 字段，但值为 null。注意：如果流被中断，您可能不会收到包含请求总令牌使用量的最终使用块。 | #### `response_format` - 类型：对象 - 必需：否 指定模型必须输出的格式。 - 设置为 `{ "type": "json_schema", "json_schema": {...} }` 启用结构化输出，确保模型将匹配您提供的 JSON schema。 - 设置为 `{ "type": "json_object" }` 启用 JSON 模式，确保模型生成的消息是有效的 JSON。 重要提示：使用 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` - 类型：整数或 null - 必需：否 Beta 功能。如果指定，我们的系统将尽最大努力进行确定性采样，使得具有相同 seed 和参数的重复请求应返回相同的结果。不保证确定性，您应参考响应参数的 system_fingerprint 以监控后端的变化。 #### `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` - 类型：数组 - 必需：否 - 注意：已弃用，推荐使用 `tools` 模型可能生成 JSON 输入的函数列表。 | 属性 | 类型 | 必需 | 描述 | |------|------|------|------| | `name` | 字符串 | 是 | 要调用的函数名称。必须是a-z、A-Z、0-9，或包含下划线和破折号，最大长度为64。 | | `description` | 字符串 | 否 | 函数功能的描述，模型用它来选择何时以及如何调用函数。 | | `parameters` | 对象 | 否 | 函数接受的参数，描述为JSON Schema对象。省略parameters定义一个空参数列表的函数。 | #### `tool_choice` - 类型：字符串或对象 - 必需：否 控制模型调用哪个工具（如果有）： - `none`：模型不会调用任何工具，而是生成消息 - `auto`：模型可以在生成消息或调用一个或多个工具之间选择 - `required`：模型必须调用一个或多个工具 - `{"type": "function", "function": {"name": "my_function"}}`：强制模型调用特定工具 当没有工具时默认为 `none`，有工具时默认为 `auto`。 **可能的类型：** | 类型 | 描述 | |------|------| | **字符串** | none 表示模型不会调用任何工具，而是生成消息。auto 表示模型可以在生成消息或调用一个或多个工具之间选择。required 表示模型必须调用一个或多个工具。 | | **对象** | 指定模型应使用的工具。用于强制模型调用特定函数。 | **对象属性：** | 属性 | 类型 | 必需 | 描述 | |------|------|------|------| | `function` | 对象 | 是 | 包含函数信息的对象 | | `type` | 字符串 | 是 | 工具的类型。目前，仅支持 function。 | **function 属性：** | 属性 | 类型 | 必需 | 描述 | |------|------|------|------| | `name` | 字符串 | 是 | 要调用的函数名称。 | #### `function_call` - 类型：字符串或对象 - 必需：否 - 默认值：没有函数时为 `none`，有函数时为 `auto` - 注意：已弃用，推荐使用 `tool_choice` 控制模型调用哪个函数（如果有）： - `none`：模型不会调用函数，而是生成消息 - `auto`：模型可以在生成消息或调用函数之间选择 - `{"name": "my_function"}`：强制模型调用特定函数 **对象类型属性：** | 属性 | 类型 | 必需 | 描述 | |------|------|------|------| | `name` | 字符串 | 是 | 要调用的函数名称。 | #### `parallel_tool_calls` - 类型：布尔值 - 必需：否 - 默认值：true 是否在工具使用期间启用并行函数调用。 #### `stream` - 类型：布尔值或 null - 必需：否 - 默认值：false 如果设置为 true，模型响应数据将在生成时通过服务器发送事件流式传输到客户端。请参阅下方的流式响应部分获取更多信息，以及流式响应指南了解如何处理流式事件。 #### `top_logprobs` - 类型：整数或 null - 必需：否 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` - 类型：字符串 - 说明：对象类型,值为 "chat.completion" #### `created` - 类型：整数 - 说明：响应创建时间戳 #### `model` - 类型：字符串 - 说明：使用的模型名称 #### `system_fingerprint` - 类型：字符串 - 说明：系统指纹标识符，表示模型运行的后端配置。可以与seed请求参数一起使用，以了解何时进行了可能影响确定性的后端更改。 #### `choices` - 类型：数组 - 说明：包含生成的回复选项列表。如果 n 大于 1，则可以有多个选项。 - 属性: - `index`: 选项在选项列表中的索引。 - `message`: 模型生成的聊天补全消息。 - `role`: 消息作者的角色。 - `content`: 消息的内容，可能为 null。 - `refusal`: 模型生成的拒绝消息，可能为 null。 - `annotations`: 消息的注释，在适用时提供，例如使用网络搜索工具时。 - `type`: 注释类型，URL引用时始终为 "url_citation"。 - `url_citation`: 使用网络搜索时的URL引用。 - `start_index`: URL引用在消息中的第一个字符的索引。 - `end_index`: URL引用在消息中的最后一个字符的索引。 - `url`: 网络资源的URL。 - `title`: 网络资源的标题。 - `audio`: 如果请求了音频输出模态，此对象包含来自模型的音频响应的数据。 - `data`: 模型生成的Base64编码音频字节，格式在请求中指定。 - `id`: 此音频响应的唯一标识符。 - `transcript`: 模型生成的音频的转录。 - `expires_at`: 此音频响应在服务器上可用于多轮对话的Unix时间戳（秒）。 - `function_call`: （已弃用）应调用的函数的名称和参数，由模型生成。已被 `tool_calls` 替代。 - `name`: 要调用的函数的名称。 - `arguments`: 用于调用函数的参数，由模型以JSON格式生成。 - `tool_calls`: 模型生成的工具调用，如函数调用。 - `id`: 工具调用的ID。 - `type`: 工具的类型。目前，仅支持 function。 - `function`: 模型调用的函数。 - `name`: 要调用的函数的名称。 - `arguments`: 用于调用函数的参数，由模型以JSON格式生成。注意，模型并不总是生成有效的JSON，并且可能会产生您函数架构中未定义的参数。在调用函数之前，请在代码中验证参数。 - `logprobs`: 对数概率信息。 - `content`: 带有对数概率信息的消息内容标记列表。 - `token`: 标记。 - `logprob`: 此标记的对数概率，如果它在前20个最可能的标记内。否则，使用-9999.0的值表示此标记非常不可能。 - `bytes`: 表示标记的UTF-8字节表示的整数列表。在字符由多个标记表示且必须组合它们的字节表示以生成正确的文本表示的情况下很有用。如果标记没有字节表示，则可能为null。 - `top_logprobs`: 在此标记位置上最可能的标记及其对数概率的列表。在罕见情况下，返回的top_logprobs数量可能少于请求的数量。 - `refusal`: 带有对数概率信息的消息拒绝标记列表。 - `finish_reason`: 模型停止生成标记的原因。如果模型到达自然停止点或提供的停止序列，则为 "stop"；如果达到请求中指定的最大标记数，则为 "length"；如果由于内容过滤器标记而省略内容，则为 "content_filter"；如果模型调用了工具，则为 "tool_calls"；如果模型调用了函数，则为 "function_call"（已弃用）。 #### `usage` - 类型：对象 - 说明：补全请求的使用统计信息。 - 属性: - `prompt_tokens`: 提示中的标记数。 - `completion_tokens`: 生成的补全中的标记数。 - `total_tokens`: 请求中使用的标记总数（提示 + 补全）。 - `prompt_tokens_details`: 提示中使用的标记的细分。 - `cached_tokens`: 提示中存在的缓存标记。 - `audio_tokens`: 提示中存在的音频输入标记。 - `completion_tokens_details`: 补全中使用的标记的细分。 - `reasoning_tokens`: 模型生成的推理标记。 - `audio_tokens`: 模型生成的音频标记。 - `accepted_prediction_tokens`: 使用预测输出时，预测中出现在补全中的标记数。 - `rejected_prediction_tokens`: 使用预测输出时，预测中未出现在补全中的标记数。但是，与推理标记一样，这些标记仍计入计费、输出和上下文窗口限制的总补全标记中。 #### `service_tier` - 类型：字符串或 null - 说明：指定用于处理请求的延迟层级。此参数与订阅了 scale tier 服务的客户相关： - 如果设置为 'auto'，且项目启用了 Scale tier，系统将使用 scale tier 信用直到用完 - 如果设置为 'auto'，且项目未启用 Scale tier，请求将使用默认服务层级处理，具有较低的正常运行时间 SLA 且无延迟保证 - 如果设置为 'default'，请求将使用默认服务层级处理，具有较低的正常运行时间 SLA 且无延迟保证 - 如果设置为 'flex'，请求将使用 Flex Processing 服务层级处理 - 未设置时，默认行为为 'auto' - 当设置此参数时，响应体将包含使用的 service_tier #### 聊天补全对象响应示例 ```json { "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` - 类型：字符串 - 说明：对象类型，始终为 "list" #### `data` - 类型：数组 - 说明：聊天补全对象的数组 #### `first_id` - 类型：字符串 - 说明：数据数组中第一个聊天补全的标识符 #### `last_id` - 类型：字符串 - 说明：数据数组中最后一个聊天补全的标识符 #### `has_more` - 类型：布尔值 - 说明：表示是否有更多聊天补全可用 #### 聊天补全列表响应示例 ```json { "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` - 类型：字符串 - 说明：对象类型，始终为 "list" #### `data` - 类型：数组 - 说明：聊天补全消息对象的数组，每个消息对象包含以下属性： - `id`: 聊天消息的标识符 - `role`: 消息作者的角色 - `content`: 消息的内容，可能为 null - `name`: 消息发送者的名称，可能为 null - `refusal`: 模型生成的拒绝消息，可能为 null - `annotations`: 消息的注释，在适用时提供，例如使用网络搜索工具时 - `type`: 注释类型，URL引用时始终为 "url_citation" - `url_citation`: 使用网络搜索时的URL引用 - `start_index`: URL引用在消息中的第一个字符的索引 - `end_index`: URL引用在消息中的最后一个字符的索引 - `url`: 网络资源的URL - `title`: 网络资源的标题 - `audio`: 如果请求了音频输出模态，此对象包含来自模型的音频响应的数据 - `data`: 模型生成的Base64编码音频字节，格式在请求中指定 - `id`: 此音频响应的唯一标识符 - `transcript`: 模型生成的音频的转录 - `expires_at`: 此音频响应在服务器上可用于多轮对话的Unix时间戳（秒） - `function_call`: （已弃用）应调用的函数的名称和参数，由模型生成。已被 `tool_calls` 替代 - `name`: 要调用的函数的名称 - `arguments`: 用于调用函数的参数，由模型以JSON格式生成 - `tool_calls`: 模型生成的工具调用，如函数调用 - `id`: 工具调用的ID - `type`: 工具的类型。目前，仅支持 function - `function`: 模型调用的函数 - `name`: 要调用的函数的名称 - `arguments`: 用于调用函数的参数，由模型以JSON格式生成 #### `first_id` - 类型：字符串 - 说明：数据数组中第一个聊天消息的标识符 #### `last_id` - 类型：字符串 - 说明：数据数组中最后一个聊天消息的标识符 #### `has_more` - 类型：布尔值 - 说明：表示是否有更多聊天消息可用 #### 聊天补全消息列表响应示例 ```json { "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 Responses](https://platform.openai.com/docs/api-reference/responses) ## 📝 简介 OpenAI 最先进的模型响应接口。支持文本和图像输入，以及文本输出。创建与模型的有状态交互，将先前响应的输出用作输入。通过文件搜索、网络搜索、计算机使用等内置工具扩展模型的能力。使用函数调用允许模型访问外部系统和数据。 相关指南可参阅OpenAI官网：[Responses](https://platform.openai.com/docs/guides/responses) ## 💡 请求示例 ### 基础文本响应 ✅ ```bash curl https://$Burncloud_API_BaseUrl/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $Burncloud_API_KEY" \ -d '{ "model": "gpt-4.1", "input": "讲一个三句话的关于独角兽的睡前故事。" }' ``` **响应示例:** ```json { "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": {} } ``` ### 图像分析响应 ✅ ```bash 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" } ] } ] }' ``` **响应示例:** ```json { "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": {} } ``` ### 网络搜索工具 ✅ ```bash 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": "今天有什么积极正面的新闻?" }' ``` **响应示例:** ```json { "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": {} } ``` ### 文件搜索工具 ✅ ```bash 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": "古代棕龙有哪些特性和属性?" }' ``` **响应示例:** ```json { "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": {} } ``` ### 流式响应 ✅ ```bash 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":{}}} ``` ### 函数调用 ✅ ```bash 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" }' ``` **响应示例:** ```json { "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": {} } ``` ### 推理能力 ✅ ```bash 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" } }' ``` **响应示例:** ```json { "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` 参数来指定使用哪个工具。 你可以提供给模型的两类工具是： - **内置工具**：由OpenAI提供的扩展模型能力的工具，如网络搜索或文件搜索。 - **函数调用（自定义工具）**：由您定义的函数，使模型能够调用您自己的代码。 ##### 文件搜索工具 (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 - 类型：字符串 - 说明：对象类型,值为 "response" #### created_at - 类型：整数 - 说明：响应创建时间戳 #### status - 类型：字符串 - 说明：响应状态，如 "completed"、"in_progress" 等 #### error - 类型：对象或null - 说明：如果发生错误，包含错误信息 #### incomplete_details - 类型：对象或null - 说明：如果响应不完整，包含详细信息 #### instructions - 类型：字符串或null - 说明：提供给模型的系统指令 #### max_output_tokens - 类型：整数或null - 说明：最大输出标记数 #### model - 类型：字符串 - 说明：使用的模型名称 #### output - 类型：数组 - 说明：包含生成的回复和工具调用 - 可能包含: - 消息对象（`type`: "message"） - 工具使用对象（`type`: "tool_use"） #### parallel_tool_calls - 类型：布尔值 - 说明：是否启用并行工具调用 #### previous_response_id - 类型：字符串或null - 说明：前一个响应的ID（用于多轮对话） #### reasoning - 类型：对象 - 说明：推理相关信息 #### store - 类型：布尔值 - 说明：是否存储此响应 #### temperature - 类型：数字 - 说明：使用的采样温度 #### text - 类型：对象 - 说明：文本输出格式配置 #### tool_choice - 类型：字符串 - 说明：工具选择策略 #### tools - 类型：数组 - 说明：可用工具列表 #### top_p - 类型：数字 - 说明：核采样阈值 #### truncation - 类型：字符串 - 说明：截断策略 #### usage - 类型：对象 - 说明：token 使用统计 - 属性: - `input_tokens`: 输入使用的 token 数 - `input_tokens_details`: 输入token详细信息 - `output_tokens`: 输出使用的 token 数 - `output_tokens_details`: 输出token详细信息 - `total_tokens`: 总 token 数 #### user - 类型：字符串或null - 说明：用户标识符 #### metadata - 类型：对象 - 说明：附加的元数据信息 # Anthropic 对话格式（Messages） 官方文档 - [Anthropic Messages](https://docs.anthropic.com/en/api/messages) - [Anthropic Streaming Messages](https://docs.anthropic.com/en/api/messages-streaming) ## 📝 简介 给定一组包含文本和/或图像内容的结构化输入消息列表，模型将生成对话中的下一条消息。Messages API 可用于单次查询或无状态的多轮对话。 ## 💡 请求示例 ### 基础文本对话 ✅ ```bash 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"} ] }' ``` **响应示例:** ```json { "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 } } ``` ### 图像分析对话 ✅ ```bash 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": "这张图片里有什么?" } ] } ] }' ``` **响应示例:** ```json { "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 } } ``` ### 工具调用 ✅ ```bash 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"] } } ] }' ``` **响应示例:** ```json { "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 } } ``` ### 流式响应 ✅ ```bash 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 }' ``` **响应示例:** ```json { "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` 字段。您可以指定单个用户角色消息，或包含多个用户和助手消息。如果最后一条消息使用助手角色，响应内容将直接从该消息的内容继续，这可以用来约束模型的响应。 **单条用户消息示例:** ```json [{"role": "user", "content": "Hello, Claude"}] ``` **多轮对话示例:** ```json [ {"role": "user", "content": "你好。"}, {"role": "assistant", "content": "你好！我是 Claude。有什么可以帮你的吗？"}, {"role": "user", "content": "请用简单的话解释什么是 LLM？"} ] ``` **部分填充的响应示例:** ```json [ {"role": "user", "content": "太阳的希腊语名字是什么? (A) Sol (B) Helios (C) Sun"}, {"role": "assistant", "content": "正确答案是 ("} ] ``` 每个消息的 content 可以是字符串或内容块数组。使用字符串相当于一个 "text" 类型的内容块数组的简写。以下两种写法等效： ```json {"role": "user", "content": "Hello, Claude"} ``` ```json { "role": "user", "content": [{"type": "text", "text": "Hello, Claude"}] } ``` 从 Claude 3 模型开始，您还可以发送图片内容块： ```json { "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` - 类型：枚举字符串 - 必需：是 - 可选值：user, assistant 注意：Messages API 中没有 "system" 角色，如果需要系统提示，请使用顶层的 system 参数。 ##### `messages.content` - 类型：字符串或对象数组 - 必需：是 消息内容可以是以下几种类型之一： ###### 文本内容 (Text) ```json { "type": "text", // 必需，枚举值: "text" "text": "Hello, Claude", // 必需，最小长度: 1 "cache_control": { "type": "ephemeral" // 可选，枚举值: "ephemeral" } } ``` ###### 图片内容 (Image) ```json { "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) ```json { "type": "tool_use", // 必需，枚举值: "tool_use"，默认值 "id": "toolu_xyz...", // 必需，工具使用的唯一标识符 "name": "get_weather", // 必需，工具名称，最小长度: 1 "input": { // 必需，工具的输入参数对象 // 工具输入参数，具体格式由工具的 input_schema 定义 }, "cache_control": { "type": "ephemeral" // 可选，枚举值: "ephemeral" } } ``` ###### 工具结果 (Tool Result) ```json { "type": "tool_result", // 必需，枚举值: "tool_result" "tool_use_id": "toolu_xyz...", // 必需 "content": "结果内容", // 必需，可以是字符串或内容块数组 "is_error": false, // 可选，布尔值 "cache_control": { "type": "ephemeral" // 可选，枚举值: "ephemeral" } } ``` 当 content 为内容块数组时，每个内容块可以是文本或图片： ```json { "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) ```json { "type": "document", // 必需，枚举值: "document" "source": { // 必需 // 文档源数据 }, "cache_control": { "type": "ephemeral" // 可选，枚举值: "ephemeral" } } ``` 注意： 1. 每种类型都可以包含可选的 `cache_control` 字段，用于控制内容的缓存行为 2. 文本内容的最小长度为 1 3. 所有类型的 type 字段都是必需的枚举字符串 4. 工具结果的 content 字段支持字符串或包含文本/图片的内容块数组 #### `model` - 类型：字符串 - 必需：是 要使用的模型名称，详见模型文档。范围 `1 - 256` 个字符。 #### `metadata` - 类型：对象 - 必需：否 描述请求元数据的对象。包含以下可选字段： - `user_id`: 与请求关联的用户的外部标识符。应该是 uuid、哈希值或其他不透明标识符。不要包含任何标识信息如姓名、邮箱或电话号码。最大长度：256。 #### `stop_sequences` - 类型：字符串数组 - 必需：否 自定义的停止生成的文本序列。 #### `stream` - 类型：布尔值 - 必需：否 是否使用服务器发送事件 (SSE) 来增量返回响应内容。 #### `system` - 类型：字符串 - 必需：否 系统 prompt，为 Claude 提供背景和指令。这是一种为模型提供上下文和特定目标或角色的方式。注意这与消息中的 role 不同，Messages API 中没有 "system" 角色。 #### `temperature` - 类型：数字 - 必需：否 - 默认值：1.0 控制生成随机性，0.0 - 1.0。范围 `0 < x < 1`。建议对于分析性/选择题类任务使用接近 0.0 的值，对于创造性和生成性任务使用接近 1.0 的值。 注意：即使 temperature 设置为 0.0，结果也不会完全确定。 #### 🆕 `thinking` - 类型：对象 - 必需：否 配置 Claude 的扩展思考功能。启用时，响应将包含展示 Claude 在给出最终答案前的思考过程的内容块。需要至少 1,024 个 token 的预算，并计入您的 max_tokens 限制。 可以设置为以下两种模式之一： ##### 1. 启用模式 ```json { "type": "enabled", "budget_tokens": 2048 } ``` - `type`: 必需，枚举值: "enabled" - `budget_tokens`: 必需，整数。决定 Claude 可以用于内部推理过程的 token 数量。更大的预算可以让模型对复杂问题进行更深入的分析，提高响应质量。必须 ≥1024 且小于 max_tokens。范围 `x > 1024`。 ##### 2. 禁用模式 ```json { "type": "disabled" } ``` - `type`: 必需，枚举值: "disabled" #### `tool_choice` - 类型：对象 - 必需：否 控制模型如何使用提供的工具。可以是以下三种类型之一： ##### 1. Auto 模式 (自动选择) ```json { "type": "auto", // 必需，枚举值: "auto" "disable_parallel_tool_use": false // 可选，默认 false。如果为 true，模型最多只会使用一个工具 } ``` ##### 2. Any 模式 (任意工具) ```json { "type": "any", // 必需，枚举值: "any" "disable_parallel_tool_use": false // 可选，默认 false。如果为 true，模型将恰好使用一个工具 } ``` ##### 3. Tool 模式 (指定工具) ```json { "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`: 工具名称，必需，1-64 个字符 - `description`: 工具描述，建议尽可能详细 - `input_schema`: 工具输入的 JSON Schema 定义，必需 - `cache_control`: 缓存控制，可选，type 为 "ephemeral" 示例： ```json [ { "type": "custom", "name": "get_weather", "description": "获取指定位置的当前天气", "input_schema": { "type": "object", "properties": { "location": { "type": "string", "description": "城市名称,如:北京" } }, "required": ["location"] } } ] ``` ##### 2. 计算机工具 (ComputerUseTool) ```json { "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) ```json { "type": "bash_20241022", // 必需 "name": "bash", // 必需，枚举值: "bash" "cache_control": { "type": "ephemeral" // 可选 } } ``` ##### 4. 文本编辑器工具 (TextEditor) ```json { "type": "text_editor_20241022", // 必需 "name": "str_replace_editor", // 必需，枚举值: "str_replace_editor" "cache_control": { "type": "ephemeral" // 可选 } } ``` 当模型使用工具时，会返回 tool_use 内容块： ```json [ { "type": "tool_use", "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "name": "get_weather", "input": { "location": "北京" } } ] ``` 您可以执行工具并通过 tool_result 内容块返回结果： ```json [ { "type": "tool_result", "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "content": "北京当前天气晴朗，温度 25°C" } ] ``` #### `top_k` - 类型：整数 - 必需：否 - 范围：x > 0 从 token 的前 K 个选项中采样。用于移除低概率的"长尾"响应。建议仅在高级用例中使用，通常只需要调整 temperature。 #### `top_p` - 类型：数字 - 必需：否 - 范围：0 < x < 1 使用 nucleus 采样。计算每个后续 token 按概率降序排列的累积分布，在达到 top_p 指定的概率时截断。建议仅调整 temperature 或 top_p 其中之一，不要同时使用。 ## 📥 响应 ### 成功响应 返回一个聊天补全对象，包含以下字段： #### `content` - 类型：对象数组 - 必需：是 模型生成的内容，由多个内容块组成。每个内容块都有一个确定其形状的 type。内容块可以是以下类型之一： ##### 文本内容块 (Text) ```json { "type": "text", // 必需，枚举值: "text"，默认值 "text": "你好，我是 Claude。" // 必需，最大长度: 5000000，最小长度: 1 } ``` ##### 工具使用内容块 (Tool Use) ```json { "type": "tool_use", // 必需，枚举值: "tool_use"，默认值 "id": "toolu_xyz...", // 必需，工具使用的唯一标识符 "name": "get_weather", // 必需，工具名称，最小长度: 1 "input": { // 必需，工具的输入参数对象 // 工具输入参数，具体格式由工具的 input_schema 定义 } } ``` 示例： ```json // 文本内容示例 [{"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": "北京" } } ] ``` 如果请求的最后一条消息是助手角色，响应内容会直接从该消息继续。例如： ```json // 请求 [ {"role": "user", "content": "太阳的希腊语名字是什么? (A) Sol (B) Helios (C) Sun"}, {"role": "assistant", "content": "正确答案是 ("} ] // 响应 [{"type": "text", "text": "B)"}] ``` #### `id` - 类型：字符串 - 必需：是 响应的唯一标识符。 #### `model` - 类型：字符串 - 必需：是 使用的模型名称。 #### `role` - 类型：枚举字符串 - 必需：是 - 默认值：assistant 生成消息的会话角色，始终为 "assistant"。 #### `stop_reason` - 类型：枚举字符串或 null - 必需：是 停止生成的原因，可能的值包括： - `"end_turn"`: 模型达到自然停止点 - `"max_tokens"`: 超过请求的 max_tokens 或模型的最大限制 - `"stop_sequence"`: 生成了自定义停止序列之一 - `"tool_use"`: 模型调用了一个或多个工具 在非流式模式下，此值始终非空。在流式模式下，在 message_start 事件中为 null，其他情况下非空。 #### `stop_sequence` - 类型：字符串或 null - 必需：是 生成的自定义停止序列。如果模型遇到了 stop_sequences 参数中指定的某个序列，这个字段将包含该匹配的停止序列。如果不是因为停止序列而停止，则为 null。 #### `type` - 类型：枚举字符串 - 必需：是 - 默认值：message - 可选值：message 对象类型，对于 Messages 始终为 "message"。 #### `usage` - 类型：对象 - 必需：是 计费和限流相关的使用量统计。包含以下字段： - `input_tokens`: 使用的输入 token 数量，必需，范围 x > 0 - `output_tokens`: 使用的输出 token 数量，必需，范围 x > 0 - `cache_creation_input_tokens`: 创建缓存条目使用的输入 token 数量(如果适用)，必需，范围 x > 0 - `cache_read_input_tokens`: 从缓存读取的输入 token 数量(如果适用)，必需，范围 x > 0 注意：由于 API 在内部会对请求进行转换和解析，token 计数可能与请求和响应的实际可见内容不完全对应。例如，即使是空字符串响应，output_tokens 也会是非零值。 ### 错误响应 当请求出现问题时，API 将返回一个错误响应对象，HTTP 状态码在 4XX-5XX 范围内。 #### 常见错误状态码 - `401 Unauthorized`: API 密钥无效或未提供 - `400 Bad Request`: 请求参数无效 - `429 Too Many Requests`: 超出 API 调用限制 - `500 Internal Server Error`: 服务器内部错误 错误响应示例: ```json { "error": { "type": "invalid_request_error", "message": "Invalid API key provided", "code": "invalid_api_key" } } ``` 主要错误类型: - `invalid_request_error`: 请求参数错误 - `authentication_error`: 认证相关错误 - `rate_limit_error`: 请求频率超限 - `server_error`: 服务器内部错误 # Deepseek reasoning 对话格式（Reasoning Content） 官方文档 - [推理模型 (deepseek-reasoner)](https://api-docs.deepseek.com/zh-cn/guides/reasoning_model) ## 📝 简介 Deepseek-reasoner 是 DeepSeek 推出的推理模型。在输出最终回答之前，模型会先输出一段思维链内容，以提升最终答案的准确性。API 向用户开放 deepseek-reasoner 思维链的内容，以供用户查看、展示、蒸馏使用。 ## 💡 请求示例 ### 基础文本对话 ✅ ```bash 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 }' ``` **响应示例:** ```json { "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 } } ``` ### 流式响应 ✅ ```bash 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 }' ``` **流式响应示例:** ```jsonl {"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` - 类型：字符串 - 必需：是 - 值：deepseek-reasoner 要使用的模型 ID。目前仅支持 deepseek-reasoner。 #### `max_tokens` - 类型：整数 - 必需：否 - 默认值：4096 - 最大值：8192 最终回答的最大长度（不含思维链输出）。请注意，思维链的输出最多可以达到 32K tokens。 #### `stream` - 类型：布尔值 - 必需：否 - 默认值：false 是否使用流式响应。 ### 不支持的参数 以下参数当前不支持: - temperature - top_p - presence_penalty - frequency_penalty - logprobs - top_logprobs 注意:为了兼容已有软件,设置 temperature、top_p、presence_penalty、frequency_penalty 参数不会报错,但也不会生效。设置 logprobs、top_logprobs 会报错。 ### 支持的功能 - 对话补全 - 对话前缀续写 (Beta) ### 不支持的功能 - Function Call - Json Output - FIM 补全 (Beta) ## 📥 响应 ### 成功响应 返回一个聊天补全对象，如果请求被流式传输，则返回聊天补全块对象的流式序列。 #### `id` - 类型：字符串 - 说明：响应的唯一标识符 #### `object` - 类型：字符串 - 说明：对象类型,值为 "chat.completion" #### `created` - 类型：整数 - 说明：响应创建时间戳 #### `model` - 类型：字符串 - 说明：使用的模型名称,值为 "deepseek-reasoner" #### `choices` - 类型：数组 - 说明：包含生成的回复选项 - 属性: - `index`: 选项索引 - `message`: 包含角色、思维链内容和最终回答的消息对象 - `role`: 角色,值为 "assistant" - `reasoning_content`: 思维链内容 - `content`: 最终回答内容 - `finish_reason`: 完成原因 #### `usage` - 类型：对象 - 说明：token 使用统计 - 属性: - `prompt_tokens`: 提示使用的 token 数 - `completion_tokens`: 补全使用的 token 数 - `total_tokens`: 总 token 数 ## 📝 上下文拼接说明 在每一轮对话过程中，模型会输出思维链内容（reasoning_content）和最终回答（content）。在下一轮对话中，之前轮输出的思维链内容不会被拼接到上下文中，如下图所示： ![Deepseek reasoning 上下文拼接示意图](/uploads/images/gallery/2025-08/deepseek-r1-multiround-example-cn.png) !!! warning "注意" 如果您在输入的 messages 序列中，传入了reasoning_content，API 会返回 400 错误。因此，请删除 API 响应中的 reasoning_content 字段，再发起 API 请求，方法如下方使用示例所示。 使用示例: ```python from openai import OpenAI client = OpenAI(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 ) ``` 流式响应示例: ```python # 第一轮对话 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 Generating content API](https://ai.google.dev/api/generate-content) ## 📝 简介 Google Gemini API 支持使用图片、音频、代码、工具等生成内容。给定输入 GenerateContentRequest 生成模型响应。支持文本生成、视觉理解、音频处理、长上下文、代码执行、JSON 模式、函数调用等多种功能。 ## 💡 请求示例 ### 基础文本对话 ✅ ```bash 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 ``` ### 图像分析对话 ✅ ```bash # 使用临时文件保存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 ``` ### 函数调用 ✅ ```bash 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 模式响应 ✅ ```bash 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。 ```bash # 使用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。 ```bash # 使用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。 ```bash 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" ``` ### 聊天对话 ✅ ```bash 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" ``` ### 流式响应 ✅ ```bash 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": "写一个关于魔法背包的故事"}] }] }' ``` ### 代码执行 ✅ ```bash 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": {} }] }' ``` ### 生成配置 ✅ ```bash 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" ``` ### 安全设置 ✅ ```bash 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 ``` ### 系统指令 ✅ ```bash 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 枚举值：** - `MODE_UNSPECIFIED`: 默认模式，模型决定是否调用函数 - `AUTO`: 模型自动决定何时调用函数 - `ANY`: 模型必须调用函数 - `NONE`: 模型不能调用函数 #### `safetySettings` - 类型：数组 - 必需：否 用于屏蔽不安全内容的 SafetySetting 实例列表。 **SafetySetting 对象属性：** | 属性 | 类型 | 必需 | 描述 | |------|------|------|------| | `category` | 枚举 | 是 | 安全类别 | | `threshold` | 枚举 | 是 | 屏蔽阈值 | **HarmCategory 枚举值：** - `HARM_CATEGORY_HARASSMENT`: 骚扰内容 - `HARM_CATEGORY_HATE_SPEECH`: 仇恨言论和内容 - `HARM_CATEGORY_SEXUALLY_EXPLICIT`: 露骨色情内容 - `HARM_CATEGORY_DANGEROUS_CONTENT`: 危险内容 - `HARM_CATEGORY_CIVIC_INTEGRITY`: 可能用于破坏公民诚信的内容 **HarmBlockThreshold 枚举值：** - `BLOCK_LOW_AND_ABOVE`: 允许发布评分为 NEGLIGIBLE 的内容 - `BLOCK_MEDIUM_AND_ABOVE`: 允许发布评分为 NEGLIGIBLE 和 LOW 的内容 - `BLOCK_ONLY_HIGH`: 允许发布风险等级为 NEGLIGIBLE、LOW 和 MEDIUM 的内容 - `BLOCK_NONE`: 允许所有内容 - `OFF`: 关闭安全过滤器 **HarmBlockThreshold 完整枚举值：** - `HARM_BLOCK_THRESHOLD_UNSPECIFIED`: 未指定阈值 - `BLOCK_LOW_AND_ABOVE`: 屏蔽低概率及以上的有害内容，只允许 NEGLIGIBLE 级别的内容 - `BLOCK_MEDIUM_AND_ABOVE`: 屏蔽中等概率及以上的有害内容，允许 NEGLIGIBLE 和 LOW 级别的内容 - `BLOCK_ONLY_HIGH`: 只屏蔽高概率的有害内容，允许 NEGLIGIBLE、LOW 和 MEDIUM 级别的内容 - `BLOCK_NONE`: 不屏蔽任何内容，允许所有级别的内容 - `OFF`: 完全关闭安全过滤器 #### `systemInstruction` - 类型：对象（Content） - 必需：否 开发者设置的系统指令。目前仅支持文本。 #### `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 类型：** - `text/plain`: （默认）文本输出 - `application/json`: JSON响应 - `text/x.enum`: ENUM作为字符串响应 **Modality 枚举值：** - `TEXT`: 指示模型应返回文本 - `IMAGE`: 表示模型应返回图片 - `AUDIO`: 指示模型应返回音频 **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 枚举值：** - `TYPE_UNSPECIFIED`: 未指定类型 - `STRING`: 字符串类型 - `NUMBER`: 数字类型 - `INTEGER`: 整数类型 - `BOOLEAN`: 布尔类型 - `ARRAY`: 数组类型 - `OBJECT`: 对象类型 **支持的编程语言（ExecutableCode）：** - `LANGUAGE_UNSPECIFIED`: 未指定语言 - `PYTHON`: Python编程语言 **代码执行结果枚举（Outcome）：** - `OUTCOME_UNSPECIFIED`: 未指定结果 - `OUTCOME_OK`: 代码执行成功 - `OUTCOME_FAILED`: 代码执行失败 - `OUTCOME_DEADLINE_EXCEEDED`: 代码执行超时 #### `cachedContent` - 类型：字符串 - 必需：否 缓存的内容的名称，用于用作提供预测的上下文。格式：`cachedContents/{cachedContent}` ## 📥 响应 ### GenerateContentResponse 支持多个候选回答的模型的回答。系统会针对提示以及每个候选项报告安全分级和内容过滤。 #### `candidates` - 类型：数组 - 说明：模型的候选回答列表 **Candidate 对象属性：** | 属性 | 类型 | 描述 | |------|------|------| | `content` | 对象 | 模型返回的生成内容 | | `finishReason` | 枚举 | 模型停止生成词元的原因 | | `safetyRatings` | 数组 | 候选回答安全性的评分列表 | | `citationMetadata` | 对象 | 模型生成的候选项的引用信息 | | `tokenCount` | 整数 | 此候选项的令牌数 | | `groundingAttributions` | 数组 | 为生成有依据的回答所参考的来源提供方信息 | | `groundingMetadata` | 对象 | 候选对象的参考元数据 | | `avgLogprobs` | 数字 | 候选项的平均对数概率得分 | | `logprobsResult` | 对象 | 回答令牌和前置令牌的对数似然度得分 | | `urlRetrievalMetadata` | 对象 | 与网址情境检索工具相关的元数据 | | `urlContextMetadata` | 对象 | 与网址情境检索工具相关的元数据 | | `index` | 整数 | 响应候选列表中候选项的索引 | **FinishReason 枚举值：** - `STOP`: 模型的自然停止点或提供的停止序列 - `MAX_TOKENS`: 已达到请求中指定的词元数量上限 - `SAFETY`: 出于安全考虑，系统已标记回答候选内容 - `RECITATION`: 由于背诵原因，回答候选内容被标记 - `LANGUAGE`: 回答候选内容因使用不受支持的语言而被标记 - `OTHER`: 原因未知 - `BLOCKLIST`: 由于内容包含禁止使用的字词，因此token生成操作已停止 - `PROHIBITED_CONTENT`: 由于可能包含禁止的内容，因此token生成操作已停止 - `SPII`: 由于内容可能包含敏感的个人身份信息，因此token生成操作已停止 - `MALFORMED_FUNCTION_CALL`: 模型生成的函数调用无效 - `IMAGE_SAFETY`: 由于生成的图片违反了安全规定，因此词元生成已停止 #### `promptFeedback` - 类型：对象 - 说明：与内容过滤器相关的提示反馈 **PromptFeedback 对象属性：** | 属性 | 类型 | 描述 | |------|------|------| | `blockReason` | 枚举 | 屏蔽该提示的原因 | | `safetyRatings` | 数组 | 问题安全性的评分 | **BlockReason 枚举值：** - `BLOCK_REASON_UNSPECIFIED`: 默认值，此值未使用 - `SAFETY`: 出于安全原因，系统屏蔽了提示 - `OTHER`: 提示因未知原因被屏蔽了 - `BLOCKLIST`: 系统屏蔽了此提示，因为其中包含术语屏蔽名单中包含的术语 - `PROHIBITED_CONTENT`: 系统屏蔽了此提示，因为其中包含禁止的内容 - `IMAGE_SAFETY`: 候选图片因生成不安全的内容而被屏蔽 #### `usageMetadata` - 类型：对象 - 说明：有关生成请求令牌用量的元数据 **UsageMetadata 对象属性：** | 属性 | 类型 | 描述 | |------|------|------| | `promptTokenCount` | 整数 | 提示中的词元数 | | `cachedContentTokenCount` | 整数 | 提示的缓存部分中的词元数 | | `candidatesTokenCount` | 整数 | 所有生成的候选回答中的词元总数 | | `totalTokenCount` | 整数 | 生成请求的总令牌数 | | `toolUsePromptTokenCount` | 整数 | 工具使用提示中的词元数量 | | `thoughtsTokenCount` | 整数 | 思考模型的想法token数 | | `promptTokensDetails` | 数组 | 在请求输入中处理的模态列表 | | `candidatesTokensDetails` | 数组 | 响应中返回的模态列表 | | `cacheTokensDetails` | 数组 | 请求输入中缓存内容的模态列表 | | `toolUsePromptTokensDetails` | 数组 | 为工具使用请求输入处理的模态列表 | #### `modelVersion` - 类型：字符串 - 说明：用于生成回答的模型版本 #### `responseId` - 类型：字符串 - 说明：用于标识每个响应的ID #### 完整响应示例 ```json { "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 枚举值：** - `NEGLIGIBLE`: 内容不安全的概率可忽略不计 - `LOW`: 内容不安全的概率较低 - `MEDIUM`: 内容不安全的概率为中等 - `HIGH`: 内容不安全的概率较高 ### 引用元数据 **CitationMetadata 对象属性：** | 属性 | 类型 | 描述 | |------|------|------| | `citationSources` | 数组 | 特定回复的来源引用 | **CitationSource 对象属性：** | 属性 | 类型 | 描述 | |------|------|------| | `startIndex` | 整数 | 归因于此来源的响应片段的开始索引 | | `endIndex` | 整数 | 归因细分的结束索引（不含） | | `uri` | 字符串 | 被归因为文本部分来源的URI | | `license` | 字符串 | 被归因为片段来源的GitHub项目的许可 | ### 代码执行 当启用代码执行工具时，模型可以生成和执行代码来解决问题。 **代码执行示例响应：** ```json { "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 支持处理多种模态的输入和输出： **支持的输入模态：** - `TEXT`: 纯文本 - `IMAGE`: 图片（JPEG、PNG、WebP、HEIC、HEIF） - `AUDIO`: 音频（WAV、MP3、AIFF、AAC、OGG、FLAC） - `VIDEO`: 视频（MP4、MPEG、MOV、AVI、FLV、MPG、WEBM、WMV、3GPP） - `DOCUMENT`: 文档（PDF） **ModalityTokenCount 对象属性：** | 属性 | 类型 | 描述 | |------|------|------| | `modality` | 枚举 | 与此令牌数关联的模态 | | `tokenCount` | 整数 | 令牌数量 | **MediaResolution 枚举值：** - `MEDIA_RESOLUTION_LOW`: 低分辨率（64个令牌） - `MEDIA_RESOLUTION_MEDIUM`: 中等分辨率（256个令牌） - `MEDIA_RESOLUTION_HIGH`: 高分辨率（256个令牌进行缩放重新取景） ### 思考功能 **ThinkingConfig 对象属性：** | 属性 | 类型 | 描述 | |------|------|------| | `includeThoughts` | 布尔值 | 是否要在回答中包含思考内容 | | `thinkingBudget` | 整数 | 模型应生成的想法token的数量 | ### 语音生成 **SpeechConfig 对象属性：** | 属性 | 类型 | 描述 | |------|------|------| | `voiceConfig` | 对象 | 单声音输出的配置 | | `multiSpeakerVoiceConfig` | 对象 | 多音箱设置的配置 | | `languageCode` | 字符串 | 用于语音合成的语言代码 | **VoiceConfig 对象属性：** | 属性 | 类型 | 描述 | |------|------|------| | `prebuiltVoiceConfig` | 对象 | 要使用的预构建语音的配置 | **PrebuiltVoiceConfig 对象属性：** | 属性 | 类型 | 描述 | |------|------|------| | `voiceName` | 字符串 | 要使用的预设语音的名称 | **MultiSpeakerVoiceConfig 对象属性：** | 属性 | 类型 | 描述 | |------|------|------| | `speakerVoiceConfigs` | 数组 | 所有已启用的音箱语音 | **SpeakerVoiceConfig 对象属性：** | 属性 | 类型 | 描述 | |------|------|------| | `speaker` | 字符串 | 要使用的音箱的名称 | | `voiceConfig` | 对象 | 要使用的语音的配置 | **支持的语言代码：** - `zh-CN`: 中文（简体） - `en-US`: 英语（美国） - `ja-JP`: 日语 - `ko-KR`: 韩语 - `fr-FR`: 法语 - `de-DE`: 德语 - `es-ES`: 西班牙语 - `pt-BR`: 葡萄牙语（巴西） - `hi-IN`: 印地语 - `ar-XA`: 阿拉伯语 - `it-IT`: 意大利语 - `tr-TR`: 土耳其语 - `vi-VN`: 越南语 - `th-TH`: 泰语 - `ru-RU`: 俄语 - `pl-PL`: 波兰语 - `nl-NL`: 荷兰语 ### Logprobs 结果 **LogprobsResult 对象属性：** | 属性 | 类型 | 描述 | |------|------|------| | `topCandidates` | 数组 | 长度等于解码步骤总数 | | `chosenCandidates` | 数组 | 长度等于解码步骤总数，所选候选项不一定在topCandidates中 | **TopCandidates 对象属性：** | 属性 | 类型 | 描述 | |------|------|------| | `candidates` | 数组 | 按对数概率降序排序的候选项 | **Candidate (Logprobs) 对象属性：** | 属性 | 类型 | 描述 | |------|------|------| | `token` | 字符串 | 候选项的令牌字符串值 | | `tokenId` | 整数 | 候选项的令牌ID值 | | `logProbability` | 数字 | 候选项的对数概率 | ### URL检索功能 **UrlRetrievalMetadata 对象属性：** | 属性 | 类型 | 描述 | |------|------|------| | `urlRetrievalContexts` | 数组 | 网址检索情境列表 | **UrlRetrievalContext 对象属性：** | 属性 | 类型 | 描述 | |------|------|------| | `retrievedUrl` | 字符串 | 工具检索到的网址 | **UrlContextMetadata 对象属性：** | 属性 | 类型 | 描述 | |------|------|------| | `urlMetadata` | 数组 | 网址上下文列表 | **UrlMetadata 对象属性：** | 属性 | 类型 | 描述 | |------|------|------| | `retrievedUrl` | 字符串 | 工具检索到的网址 | | `urlRetrievalStatus` | 枚举 | 网址检索的状态 | **UrlRetrievalStatus 枚举值：** - `URL_RETRIEVAL_STATUS_SUCCESS`: 网址检索成功 - `URL_RETRIEVAL_STATUS_ERROR`: 由于出错，网址检索失败 ### 完整安全类别 **HarmCategory 完整枚举值：** - `HARM_CATEGORY_UNSPECIFIED`: 类别未指定 - `HARM_CATEGORY_DEROGATORY`: PaLM - 针对身份和/或受保护属性的负面或有害评论 - `HARM_CATEGORY_TOXICITY`: PaLM - 粗鲁、无礼或亵渎性的内容 - `HARM_CATEGORY_VIOLENCE`: PaLM - 描述描绘针对个人或团体的暴力行为的场景 - `HARM_CATEGORY_SEXUAL`: PaLM - 包含对性行为或其他淫秽内容的引用 - `HARM_CATEGORY_MEDICAL`: PaLM - 宣传未经核实的医疗建议 - `HARM_CATEGORY_DANGEROUS`: PaLM - 危险内容会宣扬、助长或鼓励有害行为 - `HARM_CATEGORY_HARASSMENT`: Gemini - 骚扰内容 - `HARM_CATEGORY_HATE_SPEECH`: Gemini - 仇恨言论和内容 - `HARM_CATEGORY_SEXUALLY_EXPLICIT`: Gemini - 露骨色情内容 - `HARM_CATEGORY_DANGEROUS_CONTENT`: Gemini - 危险内容 - `HARM_CATEGORY_CIVIC_INTEGRITY`: Gemini - 可能用于破坏公民诚信的内容 **HarmProbability 完整枚举值：** - `HARM_PROBABILITY_UNSPECIFIED`: 概率未指定 - `NEGLIGIBLE`: 内容不安全的概率可忽略不计 - `LOW`: 内容不安全的概率较低 - `MEDIUM`: 内容不安全的概率为中等 - `HIGH`: 内容不安全的概率较高 **Modality 完整枚举值：** - `MODALITY_UNSPECIFIED`: 未指定模态 - `TEXT`: 纯文本 - `IMAGE`: 图片 - `VIDEO`: 视频 - `AUDIO`: 音频 - `DOCUMENT`: 文档，例如PDF **MediaResolution 完整枚举值：** - `MEDIA_RESOLUTION_UNSPECIFIED`: 未设置媒体分辨率 - `MEDIA_RESOLUTION_LOW`: 媒体分辨率设为低（64个令牌） - `MEDIA_RESOLUTION_MEDIUM`: 媒体分辨率设为中等（256个令牌） - `MEDIA_RESOLUTION_HIGH`: 媒体分辨率设为高（使用256个令牌进行缩放重新取景） **UrlRetrievalStatus 完整枚举值：** - `URL_RETRIEVAL_STATUS_UNSPECIFIED`: 默认值，此值未使用 - `URL_RETRIEVAL_STATUS_SUCCESS`: 网址检索成功 - `URL_RETRIEVAL_STATUS_ERROR`: 由于出错，网址检索失败 ## 🔍 错误处理 ### 常见错误码 | 错误码 | 描述 | |--------|------| | `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` | 请求超时 | 减少输入大小或重试请求 | ### 错误响应示例 ```json { "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" } ] } ] } } ``` # 嵌入 Embeddings # OpenAI 格式 官方文档 - [OpenAI Embeddings](https://platform.openai.com/docs/api-reference/embeddings) ## 📝 简介 获取给定输入文本的向量表示，这些向量可以被机器学习模型和算法轻松使用。相关指南请参阅 [Embeddings Guide](https://platform.openai.com/docs/guides/embeddings)。 需要注意的是: - 某些模型可能对输入的总 token 数有限制 - 您可以使用[示例 Python 代码](https://github.com/openai/openai-cookbook/blob/main/examples/How_to_count_tokens_with_tiktoken.ipynb)来计算 token 数量 - 例如：text-embedding-ada-002 模型的输出向量维度为 1536 ## 💡 请求示例 ### 创建文本嵌入 ✅ ```bash curl https://$Burncloud_API_BaseUrl/v1/embeddings \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $Burncloud_API_KEY" \ -d '{ "input": "The food was delicious and the waiter...", "model": "text-embedding-ada-002", "encoding_format": "float" }' ``` **响应示例:** ```json { "object": "list", "data": [ { "object": "embedding", "embedding": [ 0.0023064255, -0.009327292, // ... (1536 个浮点数,用于 ada-002) -0.0028842222 ], "index": 0 } ], "model": "text-embedding-ada-002", "usage": { "prompt_tokens": 8, "total_tokens": 8 } } ``` ### 批量创建嵌入 ✅ ```bash curl https://$Burncloud_API_BaseUrl/v1/embeddings \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $Burncloud_API_KEY" \ -d '{ "input": ["The food was delicious", "The waiter was friendly"], "model": "text-embedding-ada-002", "encoding_format": "float" }' ``` **响应示例:** ```json { "object": "list", "data": [ { "object": "embedding", "embedding": [ 0.0023064255, // ... (1536 个浮点数) ], "index": 0 }, { "object": "embedding", "embedding": [ -0.008815289, // ... (1536 个浮点数) ], "index": 1 } ], "model": "text-embedding-ada-002", "usage": { "prompt_tokens": 12, "total_tokens": 12 } } ``` ## 📮 请求 ### 端点 ``` POST /v1/embeddings ``` 创建表示输入文本的嵌入向量。 ### 鉴权方法 在请求头中包含以下内容进行 API 密钥认证： ``` Authorization: Bearer $Burncloud_API_KEY ``` 其中 `$Burncloud_API_KEY` 是您的 API 密钥。 ### 请求体参数 #### `input` - 类型：字符串或数组 - 必需：是 要嵌入的输入文本,编码为字符串或 token 数组。要在单个请求中嵌入多个输入,请传递字符串数组或 token 数组的数组。输入不得超过模型的最大输入 token 数(text-embedding-ada-002 为 8192 个 token),不能为空字符串,任何数组的维度必须小于等于 2048。 #### `model` - 类型：字符串 - 必需：是 要使用的模型 ID。您可以使用 List models API 查看所有可用模型,或查看模型概述了解它们的描述。 #### `encoding_format` - 类型：字符串 - 必需：否 - 默认值：float 返回嵌入的格式。可以是 float 或 base64。 #### `dimensions` - 类型：整数 - 必需：否 生成的输出嵌入应具有的维度数。仅在 text-embedding-3 及更高版本的模型中支持。 #### `user` - 类型：字符串 - 必需：否 代表您的最终用户的唯一标识符,可以帮助 OpenAI 监控和检测滥用行为。[了解更多](https://platform.openai.com/docs/guides/safety-best-practices/end-user-ids)。 ## 📥 响应 ### 成功响应 返回嵌入对象列表。 #### `object` - 类型：字符串 - 说明：对象类型,值为 "list" #### `data` - 类型：数组 - 说明：包含嵌入对象的数组 - 属性: - `object`: 对象类型,值为 "embedding" - `embedding`: 嵌入向量,浮点数列表。向量长度取决于模型 - `index`: 嵌入在列表中的索引 #### `model` - 类型：字符串 - 说明：使用的模型名称 #### `usage` - 类型：对象 - 说明：token 使用统计 - 属性: - `prompt_tokens`: 提示使用的 token 数 - `total_tokens`: 总 token 数 ### 嵌入对象 表示由嵌入端点返回的嵌入向量。 ```json { "object": "embedding", "embedding": [ 0.0023064255, -0.009327292, // ... (ada-002 总共 1536 个浮点数) -0.0028842222 ], "index": 0 } ``` #### `index` - 类型：整数 - 说明：嵌入在列表中的索引 #### `embedding` - 类型：数组 - 说明：嵌入向量,浮点数列表。向量长度取决于模型,具体请参阅嵌入指南 #### `object` - 类型：字符串 - 说明：对象类型,始终为 "embedding" ### 错误响应 当请求出现问题时，API 将返回一个错误响应对象，HTTP 状态码在 4XX-5XX 范围内。 #### 常见错误状态码 - `401 Unauthorized`: API 密钥无效或未提供 - `400 Bad Request`: 请求参数无效，例如输入为空或超出 token 限制 - `429 Too Many Requests`: 超出 API 调用限制 - `500 Internal Server Error`: 服务器内部错误 错误响应示例: ```json { "error": { "message": "The input exceeds the maximum length. Please reduce the length of your input.", "type": "invalid_request_error", "param": "input", "code": "context_length_exceeded" } } ``` # 重排序 Rerank # Jina AI 重排序格式（Rerank） 官方文档 - [Jina AI Rerank](https://jina.ai/reranker) 标准格式 在New API中，Jina AI的rerank格式被采用为标准格式。所有其他供应商（如Xinference、Cohere等）的rerank响应都会被格式化为Jina AI的格式，以提供统一的开发体验。 ## 📝 简介 Jina AI Rerank 是一个强大的文本重排序模型，可以根据查询对文档列表进行相关性排序。该模型支持多语言，可以处理不同语言的文本内容，并为每个文档分配相关性分数。 ## 💡 请求示例 ### 基础重排序请求 ✅ ```bash curl https://$Burncloud_API_BaseUrl/v1/rerank \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $Burncloud_API_KEY" \ -d '{ "model": "jina-reranker-v2-base-multilingual", "query": "Organic skincare products for sensitive skin", "top_n": 3, "documents": [ "Organic skincare for sensitive skin with aloe vera and chamomile...", "New makeup trends focus on bold colors and innovative techniques...", "Bio-Hautpflege für empfindliche Haut mit Aloe Vera und Kamille..." ] }' ``` **响应示例:** ```json { "results": [ { "document": { "text": "Organic skincare for sensitive skin with aloe vera and chamomile..." }, "index": 0, "relevance_score": 0.8783142566680908 }, { "document": { "text": "Bio-Hautpflege für empfindliche Haut mit Aloe Vera und Kamille..." }, "index": 2, "relevance_score": 0.7624675869941711 } ], "usage": { "prompt_tokens": 815, "completion_tokens": 0, "total_tokens": 815 } } ``` ## 📮 请求 ### 端点 ``` POST /v1/rerank ``` ### 鉴权方法 在请求头中包含以下内容进行 API 密钥认证： ``` Authorization: Bearer $Burncloud_API_KEY ``` 其中 `$Burncloud_API_KEY` 是您的 API 密钥。 ### 请求体参数 #### `model` - 类型：字符串 - 必需：否 - 默认值：jina-reranker-v2-base-multilingual - 说明：要使用的重排序模型 #### `query` - 类型：字符串 - 必需：是 - 说明：用于对文档进行相关性排序的查询文本 #### `top_n` - 类型：整数 - 必需：否 - 默认值：无限制 - 说明：返回排序后的前 N 个文档 #### `documents` - 类型：字符串数组 - 必需：是 - 说明：要进行重排序的文档列表 - 限制：每个文档的长度不应超过模型的最大token限制 ## 📥 响应 ### 成功响应 #### `results` - 类型：数组 - 说明：重排序后的文档列表 - 属性： - `document`: 包含文档文本的对象 - `index`: 文档在原始列表中的索引 - `relevance_score`: 相关性分数(0-1之间) #### `usage` - 类型：对象 - 说明：token 使用统计 - 属性： - `prompt_tokens`: 提示使用的 token 数 - `completion_tokens`: 补全使用的 token 数 - `total_tokens`: 总 token 数 - `prompt_tokens_details`: 提示 token 详细信息 - `cached_tokens`: 缓存的 token 数 - `audio_tokens`: 音频 token 数 - `completion_tokens_details`: 补全 token 详细信息 - `reasoning_tokens`: 推理 token 数 - `audio_tokens`: 音频 token 数 - `accepted_prediction_tokens`: 接受的预测 token 数 - `rejected_prediction_tokens`: 拒绝的预测 token 数 ### 错误响应 当请求出现问题时，API 将返回错误响应： - `400 Bad Request`: 请求参数无效 - `401 Unauthorized`: API 密钥无效或未提供 - `429 Too Many Requests`: 请求频率超限 - `500 Internal Server Error`: 服务器内部错误 ## 💡 最佳实践 ### 查询优化建议 1. 使用清晰具体的查询文本 2. 避免过于宽泛或模糊的查询 3. 确保查询与文档使用相同的语言风格 ### 文档处理建议 1. 保持文档长度适中，不要超过模型限制 2. 确保文档内容完整且有意义 3. 可以包含多语言文档，模型支持跨语言匹配 ### 性能优化 1. 合理设置 top_n 参数以减少不必要的计算 2. 对于大量文档，考虑分批处理 3. 可以缓存常用查询的结果 ### 多语言支持 该模型支持多种语言的文档重排序，包括但不限于： - 英语 - 中文 - 德语 - 西班牙语 - 日语 - 法语 无需指定语言参数，模型会自动识别和处理不同语言的内容。 # Cohere 重排序格式（Rerank） 重要提示 cohere 的 Rerank 模型接口和 [Jina的Rerank模型接口格式](jinaai-rerank.md) 是一样的。 官方文档 - [Cohere Rerank](https://docs.cohere.com/reference/rerank) ## 📝 简介 给定查询和文本列表，重排序API将根据与查询的相关性对文本进行排序。每个文本都会被分配一个相关性分数，从而产生一个有序的数组结果。此功能特别适用于搜索和检索应用，可以优化文档的排序，帮助用户更快找到相关信息。 ## 💡 请求示例 ### 基础重排序请求 ✅ ```bash curl https://$Burncloud_API_BaseUrl/v1/rerank \ -H "Authorization: Bearer $Burncloud_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "rerank-v3.5", "query": "什么是美国的首都？", "documents": [ "内华达州的首府是卡森城。", "北马里亚纳群岛是太平洋上的一组岛屿，其首都是塞班岛。", "华盛顿特区（也称为华盛顿或特区，正式名称为哥伦比亚特区）是美国的首都。", "英语语法中的大写是在单词开头使用大写字母。英语用法与其他语言的大写不同。", "自美国成为一个国家之前，美国就存在死刑。截至2017年，在50个州中有30个州死刑合法。" ], "top_n": 3 }' ``` **响应示例:** ```json { "results": [ { "index": 2, "relevance_score": 0.999071 }, { "index": 0, "relevance_score": 0.32713068 }, { "index": 1, "relevance_score": 0.1867867 } ], "id": "07734bd2-2473-4f07-94e1-0d9f0e6843cf", "meta": { "api_version": { "version": "2", "is_experimental": false }, "billed_units": { "search_units": 1 } } } ``` ### 使用结构化数据 ✅ ```bash curl https://$Burncloud_API_BaseUrl/v1/rerank \ -H "Authorization: Bearer $Burncloud_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "rerank-v3.5", "query": "寻找适合初学者的高性价比单反相机", "documents": [ "型号: Canon EOS 800D\n价格: 4299元\n功能: 2410万像素, 光学取景器, Wi-Fi\n适合人群: 初学者, 爱好者", "型号: Nikon D3500\n价格: 3099元\n功能: 2416万像素, 光学取景器, 长达1550张的电池续航\n适合人群: 新手, 学生", "型号: Sony A7III\n价格: 12999元\n功能: 2420万像素, 全画幅, 4K视频\n适合人群: 专业摄影师, 视频创作者" ], "max_tokens_per_doc": 512 }' ``` **响应示例:** ```json { "results": [ { "index": 1, "relevance_score": 0.918472 }, { "index": 0, "relevance_score": 0.854321 }, { "index": 2, "relevance_score": 0.423156 } ], "id": "8f734bd2-2473-4f07-94e1-0d9f0e68ebfa", "meta": { "api_version": { "version": "2" }, "billed_units": { "search_units": 1 } } } ``` ## 📮 请求 ### 端点 ``` POST /v1/rerank ``` 根据与查询的相关性对文本列表进行重新排序。 ### 鉴权方法 在请求头中包含以下内容进行 API 密钥认证： ``` Authorization: Bearer $Burncloud_API_KEY ``` 其中 `$Burncloud_API_KEY` 是您的 API 密钥。 ### 请求头参数 #### `X-Client-Name` - 类型：字符串 - 必需：否 - 说明：发起请求的项目名称。 ### 请求体参数 #### `model` - 类型：字符串 - 必需：是 - 说明：要使用的模型标识符，例如 rerank-v3.5。 #### `query` - 类型：字符串 - 必需：是 - 说明：搜索查询文本。这是用户输入的问题或查询内容。 #### `documents` - 类型：字符串数组 - 必需：是 - 说明：将与查询进行比较的文本列表。为获得最佳性能，建议单个请求中不要发送超过1,000个文档。 - 注意事项： - 长文档将自动截断为 max_tokens_per_doc 指定的值 - 结构化数据应格式化为YAML字符串以获得最佳性能 #### `top_n` - 类型：整数 - 必需：否 - 说明：限制返回的重排结果数量。如果不指定，将返回所有重排结果。 #### `max_tokens_per_doc` - 类型：整数 - 必需：否 - 默认值：4096 - 说明：长文档将自动截断为指定的令牌数量。 ## 📥 响应 ### 成功响应 返回一个包含排序后文档列表的对象。 #### `results` - 类型：对象数组 - 说明：排序后的文档列表，按相关性降序排列 - 属性： - `index`: 整数，对应于原始文档列表中文档的索引 - `relevance_score`: 浮点数，相关性分数范围为[0, 1]。接近1的分数表示与查询高度相关，接近0的分数表示相关性较低 #### `id` - 类型：字符串 - 说明：请求的唯一标识符 #### `meta` - 类型：对象 - 说明：包含关于请求的元数据 - 属性： - `api_version`: 对象，包含API版本信息 - `version`: 字符串，API版本号 - `is_deprecated`: 布尔值，是否已弃用 - `is_experimental`: 布尔值，是否为实验性功能 - `billed_units`: 对象，包含计费信息 - `search_units`: 浮点数，计费的搜索单位数 - `tokens`: 对象，包含令牌使用统计 - `input_tokens`: 浮点数，作为模型输入的令牌数 - `output_tokens`: 浮点数，模型产生的令牌数 #### `warnings` - 类型：字符串数组 - 必需：否 - 说明：API返回的警告信息 ### 错误响应 当请求出现问题时，API可能返回以下HTTP状态码及相应错误： - `400 Bad Request`: 请求格式或参数错误 - `401 Unauthorized`: 未提供有效的API密钥 - `403 Forbidden`: 没有权限访问此资源 - `404 Not Found`: 请求的资源不存在 - `422 Unprocessable Entity`: 请求格式正确但包含语义错误 - `429 Too Many Requests`: 请求频率超过限制 - `500 Internal Server Error`: 服务器内部错误 - `503 Service Unavailable`: 服务暂时不可用 ## 🌟 最佳实践 ### 文档准备建议 1. **文档长度**：每个文档保持简洁明了，避免过长。长文档会被自动截断。 2. **结构化数据**：将结构化数据格式化为YAML字符串，以获得最佳性能。例如： ```yaml title: 产品名称 price: 9999元 features: - 特性1 - 特性2 ``` 3. **文档数量**：单次请求中不要超过1,000个文档，以获得最佳性能。 ### 查询优化 1. **明确具体**：制定明确、具体的查询，以获得更准确的排序结果。 2. **避免模糊查询**：尽量避免过于模糊或通用的查询词，这可能导致相关性分数差异不明显。 ### 理解相关性分数 相关性分数是归一化到[0, 1]范围内的值： - 接近1的分数表示与查询高度相关 - 接近0的分数表示相关性低 注意：不能简单地认为分数0.9的文档比分数0.45的文档相关性高2倍。相关性分数是一个相对指标，用于排序，而非绝对比较。 # Xinference 重排序格式（Rerank） 重要提示 在New API中，Xinference的rerank响应结构将被格式化为Jina的rerank响应结构，使用方式和Jina的rerank相同。**对于Dify等客户端用户**：在配置时请选择 **Jina AI** 作为供应商类型，而不是Xinference，并使用Xinference支持的模型名称。 ## 📝 简介 Xinference的重排序API与Jina AI的重排序API完全兼容。请参考[Jina AI 重排序格式（Rerank）](/books/llm-api-docs/page/jina-ai-rerank)文档了解详细的使用方法、请求参数和响应格式。 ## 💡 使用方法 使用Xinference重排序API时，只需将`model`参数设置为Xinference支持的重排序模型即可，其余参数和使用方式与Jina AI重排序API相同。 ### 示例请求 ```bash curl https://$Burncloud_API_BaseUrl/v1/rerank \ -H "Authorization: Bearer $Burncloud_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "jina-reranker-v2", "query": "什么是美国的首都？", "documents": [ "内华达州的首府是卡森城。", "北马里亚纳群岛是太平洋上的一组岛屿，其首都是塞班岛。", "华盛顿特区（也称为华盛顿或特区，正式名称为哥伦比亚特区）是美国的首都。", "英语语法中的大写是在单词开头使用大写字母。英语用法与其他语言的大写不同。", "自美国成为一个国家之前，美国就存在死刑。截至2017年，在50个州中有30个州死刑合法。" ], "top_n": 3 }' ``` 有关更多详细信息，请参考[Jina AI 重排序格式（Rerank）](/books/llm-api-docs/page/jina-ai-rerank)文档。 # 实时对话（Realtime） # OpenAI 实时对话接口 官方文档 - [OpenAI Realtime WebRTC](https://platform.openai.com/docs/guides/realtime-webrtc) - [OpenAI Realtime WebSocket](https://platform.openai.com/docs/guides/realtime-websocket) ## 📝 概述 ### 简介 OpenAI Realtime API 提供两种连接方式： 1. WebRTC - 适用于浏览器和移动客户端的实时音视频交互 2. WebSocket - 适用于服务器到服务器的应用程序集成 ### 使用场景 - 实时语音对话 - 音视频会议 - 实时翻译 - 语音转写 - 实时代码生成 - 服务器端实时集成 ### 主要特性 - 双向音频流传输 - 文本和音频混合对话 - 函数调用支持 - 自动语音检测(VAD) - 音频转写功能 - WebSocket 服务器端集成 ## 🔐 认证与安全 ### 认证方式 1. 标准 API 密钥 (仅服务器端使用) 2. 临时令牌 (客户端使用) ### 临时令牌 - 有效期: 1分钟 - 使用限制: 单个连接 - 获取方式: 通过服务器端 API 创建 ```http POST https://$Burncloud_API_BaseUrl/v1/realtime/sessions Content-Type: application/json Authorization: Bearer $NEW_API_KEY { "model": "gpt-4o-realtime-preview-2024-12-17", "voice": "verse" } ``` ### 安全建议 - 永远不要在客户端暴露标准 API 密钥 - 使用 HTTPS/WSS 进行通信 - 实现适当的访问控制 - 监控异常活动 ## 🔌 连接建立 ### WebRTC 连接 - URL: `https://$Burncloud_API_BaseUrl/v1/realtime` - 查询参数: `model` - 请求头: - `Authorization: Bearer EPHEMERAL_KEY` - `Content-Type: application/sdp` ### WebSocket 连接 - URL: `wss://$Burncloud_API_BaseUrl/v1/realtime` - 查询参数: `model` - 请求头: - `Authorization: Bearer YOUR_API_KEY` - `OpenAI-Beta: realtime=v1` ### 连接流程 [![openai-realtime](https://docs.burncloud.com/uploads/images/gallery/2025-08/scaled-1680-/9QOqq20250814143343.png)](https://docs.burncloud.com/uploads/images/gallery/2025-08/9QOqq20250814143343.png) ### 数据通道 - 名称: `oai-events` - 用途: 事件传输 - 格式: JSON ### 音频流 - 输入: `addTrack()` - 输出: `ontrack` 事件 ## 💬 对话交互 ### 对话模式 1. 纯文本对话 2. 语音对话 3. 混合对话 ### 会话管理 - 创建会话 - 更新会话 - 结束会话 - 会话配置 ### 事件类型 - 文本事件 - 音频事件 - 函数调用 - 状态更新 - 错误事件 ## ⚙️ 配置选项 ### 音频配置 - 输入格式 - `pcm16` - `g711_ulaw` - `g711_alaw` - 输出格式 - `pcm16` - `g711_ulaw` - `g711_alaw` - 语音类型 - `alloy` - `echo` - `shimmer` ### 模型配置 - 温度 - 最大输出长度 - 系统提示词 - 工具配置 ### VAD 配置 - 阈值 - 静音时长 - 前缀填充 ## 💡 请求示例 ### WebRTC 连接 ❌ #### 客户端实现 (浏览器) ```javascript async function init() { // 从服务器获取临时密钥 - 参见下方服务器代码 const tokenResponse = await fetch("/session"); const data = await tokenResponse.json(); const EPHEMERAL_KEY = data.client_secret.value; // 创建对等连接 const pc = new RTCPeerConnection(); // 设置播放模型返回的远程音频 const audioEl = document.createElement("audio"); audioEl.autoplay = true; pc.ontrack = e => audioEl.srcObject = e.streams[0]; // 添加浏览器麦克风输入的本地音频轨道 const ms = await navigator.mediaDevices.getUserMedia({ audio: true }); pc.addTrack(ms.getTracks()[0]); // 设置用于发送和接收事件的数据通道 const dc = pc.createDataChannel("oai-events"); dc.addEventListener("message", (e) => { // 这里接收实时服务器事件！ console.log(e); }); // 使用会话描述协议(SDP)启动会话 const offer = await pc.createOffer(); await pc.setLocalDescription(offer); const baseUrl = "https://$Burncloud_API_BaseUrl/v1/realtime"; const model = "gpt-4o-realtime-preview-2024-12-17"; const sdpResponse = await fetch(`${baseUrl}?model=${model}`, { method: "POST", body: offer.sdp, headers: { Authorization: `Bearer ${EPHEMERAL_KEY}`, "Content-Type": "application/sdp" }, }); const answer = { type: "answer", sdp: await sdpResponse.text(), }; await pc.setRemoteDescription(answer); } init(); ``` #### 服务器端实现 (Node.js) ```javascript import express from "express"; const app = express(); // 创建一个端点用于生成临时令牌 // 该端点与上面的客户端代码配合使用 app.get("/session", async (req, res) => { const r = await fetch("https://$Burncloud_API_BaseUrl/v1/realtime/sessions", { method: "POST", headers: { "Authorization": `Bearer ${process.env.NEW_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ model: "gpt-4o-realtime-preview-2024-12-17", voice: "verse", }), }); const data = await r.json(); // 将从OpenAI REST API收到的JSON发送回客户端 res.send(data); }); app.listen(3000); ``` #### WebRTC 事件收发示例 ```javascript // 从对等连接创建数据通道 const dc = pc.createDataChannel("oai-events"); // 监听数据通道上的服务器事件 // 事件数据需要从JSON字符串解析 dc.addEventListener("message", (e) => { const realtimeEvent = JSON.parse(e.data); console.log(realtimeEvent); }); // 发送客户端事件：将有效的客户端事件序列化为 // JSON，并通过数据通道发送 const responseCreate = { type: "response.create", response: { modalities: ["text"], instructions: "Write a haiku about code", }, }; dc.send(JSON.stringify(responseCreate)); ``` ### WebSocket 连接 ✅ #### Node.js (ws模块) ```javascript import WebSocket from "ws"; const url = "wss://$Burncloud_API_BaseUrl/v1/realtime?model=gpt-4o-realtime-preview-2024-12-17"; const ws = new WebSocket(url, { headers: { "Authorization": "Bearer " + process.env.NEW_API_KEY, "OpenAI-Beta": "realtime=v1", }, }); ws.on("open", function open() { console.log("Connected to server."); }); ws.on("message", function incoming(message) { console.log(JSON.parse(message.toString())); }); ``` #### Python (websocket-client) ```python # 需要安装 websocket-client 库: # pip install websocket-client import os import json import websocket NEW_API_KEY = os.environ.get("NEW_API_KEY") url = "wss://$Burncloud_API_BaseUrl/v1/realtime?model=gpt-4o-realtime-preview-2024-12-17" headers = [ "Authorization: Bearer " + NEW_API_KEY, "OpenAI-Beta: realtime=v1" ] def on_open(ws): print("Connected to server.") def on_message(ws, message): data = json.loads(message) print("Received event:", json.dumps(data, indent=2)) ws = websocket.WebSocketApp( url, header=headers, on_open=on_open, on_message=on_message, ) ws.run_forever() ``` #### 浏览器 (标准WebSocket) ```javascript /* 注意：在浏览器等客户端环境中，我们建议使用WebRTC。 但在Deno和Cloudflare Workers等类浏览器环境中， 也可以使用标准WebSocket接口。 */ const ws = new WebSocket( "wss://$Burncloud_API_BaseUrl/v1/realtime?model=gpt-4o-realtime-preview-2024-12-17", [ "realtime", // 认证 "openai-insecure-api-key." + NEW_API_KEY, // 可选 "openai-organization." + OPENAI_ORG_ID, "openai-project." + OPENAI_PROJECT_ID, // Beta协议，必需 "openai-beta.realtime-v1" ] ); ws.on("open", function open() { console.log("Connected to server."); }); ws.on("message", function incoming(message) { console.log(message.data); }); ``` #### 消息收发示例 ##### Node.js/浏览器 ```javascript // 接收服务器事件 ws.on("message", function incoming(message) { // 需要从JSON解析消息数据 const serverEvent = JSON.parse(message.data) console.log(serverEvent); }); // 发送事件，创建符合客户端事件格式的JSON数据结构 const event = { type: "response.create", response: { modalities: ["audio", "text"], instructions: "Give me a haiku about code.", } }; ws.send(JSON.stringify(event)); ``` ##### Python ```python # 发送客户端事件，将字典序列化为JSON def on_open(ws): print("Connected to server.") event = { "type": "response.create", "response": { "modalities": ["text"], "instructions": "Please assist the user." } } ws.send(json.dumps(event)) # 接收消息需要从JSON解析消息负载 def on_message(ws, message): data = json.loads(message) print("Received event:", json.dumps(data, indent=2)) ``` ## ⚠️ 错误处理 ### 常见错误 1. 连接错误 - 网络问题 - 认证失败 - 配置错误 2. 音频错误 - 设备权限 - 格式不支持 - 编解码问题 3. 会话错误 - 令牌过期 - 会话超时 - 并发限制 ### 错误恢复 1. 自动重连 2. 会话恢复 3. 错误重试 4. 降级处理 ## 📝 事件参考 ### 通用请求头 所有事件都需要包含以下请求头: | 请求头 | 类型 | 说明 | 示例值 | |--------|------|------|---------| | Authorization | 字符串 | 认证令牌 | Bearer $NEW_API_KEY | | OpenAI-Beta | 字符串 | API 版本 | realtime=v1 | ### 客户端事件 #### session.update 更新会话的默认配置。 | 参数 | 类型 | 必需 | 说明 | 示例值/可选值 | |------|------|------|------|---------------| | event_id | 字符串 | 否 | 客户端生成的事件标识符 | event_123 | | type | 字符串 | 否 | 事件类型 | session.update | | modalities | 字符串数组 | 否 | 模型可以响应的模态类型 | ["text", "audio"] | | instructions | 字符串 | 否 | 预置到模型调用前的系统指令 | "Your knowledge cutoff is 2023-10..." | | voice | 字符串 | 否 | 模型使用的语音类型 | alloy、echo、shimmer | | input_audio_format | 字符串 | 否 | 输入音频格式 | pcm16、g711_ulaw、g711_alaw | | output_audio_format | 字符串 | 否 | 输出音频格式 | pcm16、g711_ulaw、g711_alaw | | input_audio_transcription.model | 字符串 | 否 | 用于转写的模型 | whisper-1 | | turn_detection.type | 字符串 | 否 | 语音检测类型 | server_vad | | turn_detection.threshold | 数字 | 否 | VAD 激活阈值(0.0-1.0) | 0.8 | | turn_detection.prefix_padding_ms | 整数 | 否 | 语音开始前包含的音频时长 | 500 | | turn_detection.silence_duration_ms | 整数 | 否 | 检测语音停止的静音持续时间 | 1000 | | tools | 数组 | 否 | 模型可用的工具列表 | [] | | tool_choice | 字符串 | 否 | 模型选择工具的方式 | auto/none/required | | temperature | 数字 | 否 | 模型采样温度 | 0.8 | | max_output_tokens | 字符串/整数 | 否 | 单次响应最大token数 | "inf"/4096 | #### input_audio_buffer.append 向输入音频缓冲区追加音频数据。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 客户端生成的事件标识符 | event_456 | | type | 字符串 | 否 | 事件类型 | input_audio_buffer.append | | audio | 字符串 | 否 | Base64编码的音频数据 | Base64EncodedAudioData | #### input_audio_buffer.commit 将缓冲区中的音频数据提交为用户消息。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 客户端生成的事件标识符 | event_789 | | type | 字符串 | 否 | 事件类型 | input_audio_buffer.commit | #### input_audio_buffer.clear 清空输入音频缓冲区中的所有音频数据。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 客户端生成的事件标识符 | event_012 | | type | 字符串 | 否 | 事件类型 | input_audio_buffer.clear | #### conversation.item.create 向对话中添加新的对话项。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 客户端生成的事件标识符 | event_345 | | type | 字符串 | 否 | 事件类型 | conversation.item.create | | previous_item_id | 字符串 | 否 | 新对话项将插入在此ID之后 | null | | item.id | 字符串 | 否 | 对话项的唯一标识符 | msg_001 | | item.type | 字符串 | 否 | 对话项类型 | message/function_call/function_call_output | | item.status | 字符串 | 否 | 对话项状态 | completed/in_progress/incomplete | | item.role | 字符串 | 否 | 消息发送者的角色 | user/assistant/system | | item.content | 数组 | 否 | 消息内容 | [text/audio/transcript] | | item.call_id | 字符串 | 否 | 函数调用的ID | call_001 | | item.name | 字符串 | 否 | 被调用的函数名称 | function_name | | item.arguments | 字符串 | 否 | 函数调用的参数 | {"param": "value"} | | item.output | 字符串 | 否 | 函数调用的输出结果 | {"result": "value"} | #### conversation.item.truncate 截断助手消息中的音频内容。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 客户端生成的事件标识符 | event_678 | | type | 字符串 | 否 | 事件类型 | conversation.item.truncate | | item_id | 字符串 | 否 | 要截断的助手消息项的ID | msg_002 | | content_index | 整数 | 否 | 要截断的内容部分的索引 | 0 | | audio_end_ms | 整数 | 否 | 音频截断的结束时间点 | 1500 | #### conversation.item.delete 从对话历史中删除指定的对话项。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 客户端生成的事件标识符 | event_901 | | type | 字符串 | 否 | 事件类型 | conversation.item.delete | | item_id | 字符串 | 否 | 要删除的对话项的ID | msg_003 | #### response.create 触发响应生成。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 客户端生成的事件标识符 | event_234 | | type | 字符串 | 否 | 事件类型 | response.create | | response.modalities | 字符串数组 | 否 | 响应的模态类型 | ["text", "audio"] | | response.instructions | 字符串 | 否 | 给模型的指令 | "Please assist the user." | | response.voice | 字符串 | 否 | 模型使用的语音类型 | alloy/echo/shimmer | | response.output_audio_format | 字符串 | 否 | 输出音频格式 | pcm16 | | response.tools | 数组 | 否 | 模型可用的工具列表 | ["type", "name", "description"] | | response.tool_choice | 字符串 | 否 | 模型选择工具的方式 | auto | | response.temperature | 数字 | 否 | 采样温度 | 0.7 | | response.max_output_tokens | 整数/字符串 | 否 | 最大输出token数 | 150/"inf" | #### response.cancel 取消正在进行中的响应生成。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 客户端生成的事件标识符 | event_567 | | type | 字符串 | 否 | 事件类型 | response.cancel | ### 服务端事件 #### error 当发生错误时返回的事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串数组 | 否 | 服务端事件的唯一标识符 | ["event_890"] | | type | 字符串 | 否 | 事件类型 | error | | error.type | 字符串 | 否 | 错误类型 | invalid_request_error/server_error | | error.code | 字符串 | 否 | 错误代码 | invalid_event | | error.message | 字符串 | 否 | 人类可读的错误消息 | "The 'type' field is missing." | | error.param | 字符串 | 否 | 与错误相关的参数 | null | | error.event_id | 字符串 | 否 | 相关事件的ID | event_567 | #### conversation.item.input_audio_transcription.completed 当启用输入音频转写功能并且转写成功时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_2122 | | type | 字符串 | 否 | 事件类型 | conversation.item.input_audio_transcription.completed | | item_id | 字符串 | 否 | 用户消息项的ID | msg_003 | | content_index | 整数 | 否 | 包含音频的内容部分的索引 | 0 | | transcript | 字符串 | 否 | 转写的文本内容 | "Hello, how are you?" | #### conversation.item.input_audio_transcription.failed 当配置了输入音频转写功能,但用户消息的转写请求失败时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_2324 | | type | 字符串数组 | 否 | 事件类型 | ["conversation.item.input_audio_transcription.failed"] | | item_id | 字符串 | 否 | 用户消息项的ID | msg_003 | | content_index | 整数 | 否 | 包含音频的内容部分的索引 | 0 | | error.type | 字符串 | 否 | 错误类型 | transcription_error | | error.code | 字符串 | 否 | 错误代码 | audio_unintelligible | | error.message | 字符串 | 否 | 人类可读的错误消息 | "The audio could not be transcribed." | | error.param | 字符串 | 否 | 与错误相关的参数 | null | #### conversation.item.truncated 当客户端截断了之前的助手音频消息项时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_2526 | | type | 字符串 | 否 | 事件类型 | conversation.item.truncated | | item_id | 字符串 | 否 | 被截断的助手消息项的ID | msg_004 | | content_index | 整数 | 否 | 被截断的内容部分的索引 | 0 | | audio_end_ms | 整数 | 否 | 音频被截断的时间点(毫秒) | 1500 | #### conversation.item.deleted 当对话中的某个项目被删除时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_2728 | | type | 字符串 | 否 | 事件类型 | conversation.item.deleted | | item_id | 字符串 | 否 | 被删除的对话项的ID | msg_005 | #### input_audio_buffer.committed 当音频缓冲区中的数据被提交时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_1121 | | type | 字符串 | 否 | 事件类型 | input_audio_buffer.committed | | previous_item_id | 字符串 | 否 | 新对话项将插入在此ID对应的对话项之后 | msg_001 | | item_id | 字符串 | 否 | 将要创建的用户消息项的ID | msg_002 | #### input_audio_buffer.cleared 当客户端清空输入音频缓冲区时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_1314 | | type | 字符串 | 否 | 事件类型 | input_audio_buffer.cleared | #### input_audio_buffer.speech_started 在服务器语音检测模式下，当检测到语音输入时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_1516 | | type | 字符串 | 否 | 事件类型 | input_audio_buffer.speech_started | | audio_start_ms | 整数 | 否 | 从会话开始到检测到语音的毫秒数 | 1000 | | item_id | 字符串 | 否 | 语音停止时将创建的用户消息项的ID | msg_003 | #### input_audio_buffer.speech_stopped 在服务器语音检测模式下，当检测到语音输入停止时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_1718 | | type | 字符串 | 否 | 事件类型 | input_audio_buffer.speech_stopped | | audio_start_ms | 整数 | 否 | 从会话开始到检测到语音停止的毫秒数 | 2000 | | item_id | 字符串 | 否 | 将要创建的用户消息项的ID | msg_003 | #### response.created 当创建新的响应时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_2930 | | type | 字符串 | 否 | 事件类型 | response.created | | response.id | 字符串 | 否 | 响应的唯一标识符 | resp_001 | | response.object | 字符串 | 否 | 对象类型 | realtime.response | | response.status | 字符串 | 否 | 响应的状态 | in_progress | | response.status_details | 对象 | 否 | 状态的附加详细信息 | null | | response.output | 字符串数组 | 否 | 响应生成的输出项列表 | ["[]"] | | response.usage | 对象 | 否 | 响应的使用统计信息 | null | #### response.done 当响应完成流式传输时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_3132 | | type | 字符串 | 否 | 事件类型 | response.done | | response.id | 字符串 | 否 | 响应的唯一标识符 | resp_001 | | response.object | 字符串 | 否 | 对象类型 | realtime.response | | response.status | 字符串 | 否 | 响应的最终状态 | completed/cancelled/failed/incomplete | | response.status_details | 对象 | 否 | 状态的附加详细信息 | null | | response.output | 字符串数组 | 否 | 响应生成的输出项列表 | ["[...]"] | | response.usage.total_tokens | 整数 | 否 | 总token数 | 50 | | response.usage.input_tokens | 整数 | 否 | 输入token数 | 20 | | response.usage.output_tokens | 整数 | 否 | 输出token数 | 30 | #### response.output_item.added 当响应生成过程中创建新的输出项时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_3334 | | type | 字符串 | 否 | 事件类型 | response.output_item.added | | response_id | 字符串 | 否 | 输出项所属的响应ID | resp_001 | | output_index | 字符串 | 否 | 输出项在响应中的索引 | 0 | | item.id | 字符串 | 否 | 输出项的唯一标识符 | msg_007 | | item.object | 字符串 | 否 | 对象类型 | realtime.item | | item.type | 字符串 | 否 | 输出项类型 | message/function_call/function_call_output | | item.status | 字符串 | 否 | 输出项状态 | in_progress/completed | | item.role | 字符串 | 否 | 与输出项关联的角色 | assistant | | item.content | 数组 | 否 | 输出项的内容 | ["type", "text", "audio", "transcript"] | #### response.output_item.done 当输出项完成流式传输时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_3536 | | type | 字符串 | 否 | 事件类型 | response.output_item.done | | response_id | 字符串 | 否 | 输出项所属的响应ID | resp_001 | | output_index | 字符串 | 否 | 输出项在响应中的索引 | 0 | | item.id | 字符串 | 否 | 输出项的唯一标识符 | msg_007 | | item.object | 字符串 | 否 | 对象类型 | realtime.item | | item.type | 字符串 | 否 | 输出项类型 | message/function_call/function_call_output | | item.status | 字符串 | 否 | 输出项的最终状态 | completed/incomplete | | item.role | 字符串 | 否 | 与输出项关联的角色 | assistant | | item.content | 数组 | 否 | 输出项的内容 | ["type", "text", "audio", "transcript"] | #### response.content_part.added 当响应生成过程中向助手消息项添加新的内容部分时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_3738 | | type | 字符串 | 否 | 事件类型 | response.content_part.added | | response_id | 字符串 | 否 | 响应的ID | resp_001 | | item_id | 字符串 | 否 | 添加内容部分的消息项ID | msg_007 | | output_index | 整数 | 否 | 输出项在响应中的索引 | 0 | | content_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 | | part.type | 字符串 | 否 | 内容类型 | text/audio | | part.text | 字符串 | 否 | 文本内容 | "Hello" | | part.audio | 字符串 | 否 | Base64编码的音频数据 | "base64_encoded_audio_data" | | part.transcript | 字符串 | 否 | 音频的转写文本 | "Hello" | #### response.content_part.done 当助手消息项中的内容部分完成流式传输时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_3940 | | type | 字符串 | 否 | 事件类型 | response.content_part.done | | response_id | 字符串 | 否 | 响应的ID | resp_001 | | item_id | 字符串 | 否 | 添加内容部分的消息项ID | msg_007 | | output_index | 整数 | 否 | 输出项在响应中的索引 | 0 | | content_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 | | part.type | 字符串 | 否 | 内容类型 | text/audio | | part.text | 字符串 | 否 | 文本内容 | "Hello" | | part.audio | 字符串 | 否 | Base64编码的音频数据 | "base64_encoded_audio_data" | | part.transcript | 字符串 | 否 | 音频的转写文本 | "Hello" | #### response.text.delta 当"text"类型内容部分的文本值更新时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_4142 | | type | 字符串 | 否 | 事件类型 | response.text.delta | | response_id | 字符串 | 否 | 响应的ID | resp_001 | | item_id | 字符串 | 否 | 消息项的ID | msg_007 | | output_index | 整数 | 否 | 输出项在响应中的索引 | 0 | | content_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 | | delta | 字符串 | 否 | 文本增量更新内容 | "Sure, I can h" | #### response.text.done 当"text"类型内容部分的文本流式传输完成时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_4344 | | type | 字符串 | 否 | 事件类型 | response.text.done | | response_id | 字符串 | 否 | 响应的ID | resp_001 | | item_id | 字符串 | 否 | 消息项的ID | msg_007 | | output_index | 整数 | 否 | 输出项在响应中的索引 | 0 | | content_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 | | delta | 字符串 | 否 | 最终的完整文本内容 | "Sure, I can help with that." | #### response.audio_transcript.delta 当模型生成的音频输出转写内容更新时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_4546 | | type | 字符串 | 否 | 事件类型 | response.audio_transcript.delta | | response_id | 字符串 | 否 | 响应的ID | resp_001 | | item_id | 字符串 | 否 | 消息项的ID | msg_008 | | output_index | 整数 | 否 | 输出项在响应中的索引 | 0 | | content_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 | | delta | 字符串 | 否 | 转写文本的增量更新内容 | "Hello, how can I a" | #### response.audio_transcript.done 当模型生成的音频输出转写完成流式传输时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_4748 | | type | 字符串 | 否 | 事件类型 | response.audio_transcript.done | | response_id | 字符串 | 否 | 响应的ID | resp_001 | | item_id | 字符串 | 否 | 消息项的ID | msg_008 | | output_index | 整数 | 否 | 输出项在响应中的索引 | 0 | | content_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 | | transcript | 字符串 | 否 | 音频的最终完整转写文本 | "Hello, how can I assist you today?" | #### response.audio.delta 当模型生成的音频内容更新时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_4950 | | type | 字符串 | 否 | 事件类型 | response.audio.delta | | response_id | 字符串 | 否 | 响应的ID | resp_001 | | item_id | 字符串 | 否 | 消息项的ID | msg_008 | | output_index | 整数 | 否 | 输出项在响应中的索引 | 0 | | content_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 | | delta | 字符串 | 否 | Base64编码的音频数据增量 | "Base64EncodedAudioDelta" | #### response.audio.done 当模型生成的音频完成时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_5152 | | type | 字符串 | 否 | 事件类型 | response.audio.done | | response_id | 字符串 | 否 | 响应的ID | resp_001 | | item_id | 字符串 | 否 | 消息项的ID | msg_008 | | output_index | 整数 | 否 | 输出项在响应中的索引 | 0 | | content_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 | ### 函数调用 #### response.function_call_arguments.delta 当模型生成的函数调用参数更新时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_5354 | | type | 字符串 | 否 | 事件类型 | response.function_call_arguments.delta | | response_id | 字符串 | 否 | 响应的ID | resp_002 | | item_id | 字符串 | 否 | 消息项的ID | fc_001 | | output_index | 整数 | 否 | 输出项在响应中的索引 | 0 | | call_id | 字符串 | 否 | 函数调用的ID | call_001 | | delta | 字符串 | 否 | JSON格式的函数调用参数增量 | "{\"location\": \"San\"" | #### response.function_call_arguments.done 当模型生成的函数调用参数完成流式传输时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_5556 | | type | 字符串 | 否 | 事件类型 | response.function_call_arguments.done | | response_id | 字符串 | 否 | 响应的ID | resp_002 | | item_id | 字符串 | 否 | 消息项的ID | fc_001 | | output_index | 整数 | 否 | 输出项在响应中的索引 | 0 | | call_id | 字符串 | 否 | 函数调用的ID | call_001 | | arguments | 字符串 | 否 | 最终的完整函数调用参数(JSON格式) | "{\"location\": \"San Francisco\"}" | ### 其他状态更新 #### rate_limits.updated 在每个 "response.done" 事件之后触发,用于指示更新后的速率限制。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_5758 | | type | 字符串 | 否 | 事件类型 | rate_limits.updated | | rate_limits | 对象数组 | 否 | 速率限制信息列表 | [{"name": "requests_per_min", "limit": 60, "remaining": 45, "reset_seconds": 35}] | #### conversation.created 当对话创建时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_9101 | | type | 字符串 | 否 | 事件类型 | conversation.created | | conversation | 对象 | 否 | 对话资源对象 | {"id": "conv_001", "object": "realtime.conversation"} | #### conversation.item.created 当对话项创建时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_1920 | | type | 字符串 | 否 | 事件类型 | conversation.item.created | | previous_item_id | 字符串 | 否 | 前一个对话项的ID | msg_002 | | item | 对象 | 否 | 对话项对象 | {"id": "msg_003", "object": "realtime.item", "type": "message", "status": "completed", "role": "user", "content": [{"type": "text", "text": "Hello"}]} | #### session.created 当会话创建时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_1234 | | type | 字符串 | 否 | 事件类型 | session.created | | session | 对象 | 否 | 会话对象 | {"id": "sess_001", "object": "realtime.session", "model": "gpt-4", "modalities": ["text", "audio"]} | #### session.updated 当会话更新时返回此事件。 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 否 | 服务端事件的唯一标识符 | event_5678 | | type | 字符串 | 否 | 事件类型 | session.updated | | session | 对象 | 否 | 更新后的会话对象 | {"id": "sess_001", "object": "realtime.session", "model": "gpt-4", "modalities": ["text", "audio"]} | ### 速率限制事件参数表 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | name | 字符串 | 是 | 限制名称 | requests_per_min | | limit | 整数 | 是 | 限制值 | 60 | | remaining | 整数 | 是 | 剩余可用量 | 45 | | reset_seconds | 整数 | 是 | 重置时间(秒) | 35 | ### 函数调用参数表 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | type | 字符串 | 是 | 函数类型 | function | | name | 字符串 | 是 | 函数名称 | get_weather | | description | 字符串 | 否 | 函数描述 | Get the current weather | | parameters | 对象 | 是 | 函数参数定义 | {"type": "object", "properties": {...}} | ### 音频格式参数表 | 参数 | 类型 | 说明 | 可选值 | |------|------|------|--------| | sample_rate | 整数 | 采样率 | 8000, 16000, 24000, 44100, 48000 | | channels | 整数 | 声道数 | 1 (单声道), 2 (立体声) | | bits_per_sample | 整数 | 采样位数 | 16 (pcm16), 8 (g711) | | encoding | 字符串 | 编码方式 | pcm16, g711_ulaw, g711_alaw | ### 语音检测参数表 | 参数 | 类型 | 说明 | 默认值 | 范围 | |------|------|------|--------|------| | threshold | 浮点数 | VAD 激活阈值 | 0.5 | 0.0-1.0 | | prefix_padding_ms | 整数 | 语音前缀填充(毫秒) | 500 | 0-5000 | | silence_duration_ms | 整数 | 静音检测时长(毫秒) | 1000 | 100-10000 | ### 工具选择参数表 | 参数 | 类型 | 说明 | 可选值 | |------|------|------|--------| | tool_choice | 字符串 | 工具选择方式 | auto, none, required | | tools | 数组 | 可用工具列表 | [{type, name, description, parameters}] | ### 模型配置参数表 | 参数 | 类型 | 说明 | 范围/可选值 | 默认值 | |------|------|------|-------------|--------| | temperature | 浮点数 | 采样温度 | 0.0-2.0 | 1.0 | | max_output_tokens | 整数/字符串 | 最大输出长度 | 1-4096/"inf" | "inf" | | modalities | 字符串数组 | 响应模态 | ["text", "audio"] | ["text"] | | voice | 字符串 | 语音类型 | alloy, echo, shimmer | alloy | ### 事件通用参数表 | 参数 | 类型 | 必需 | 说明 | 示例值 | |------|------|------|------|--------| | event_id | 字符串 | 是 | 事件的唯一标识符 | event_123 | | type | 字符串 | 是 | 事件类型 | session.update | | timestamp | 整数 | 否 | 事件发生的时间戳(毫秒) | 1677649363000 | ### 会话状态参数表 | 参数 | 类型 | 说明 | 可选值 | |------|------|------|--------| | status | 字符串 | 会话状态 | active, ended, error | | error | 对象 | 错误信息 | {"type": "error_type", "message": "error message"} | | metadata | 对象 | 会话元数据 | {"client_id": "web", "session_type": "chat"} | ### 对话项状态参数表 | 参数 | 类型 | 说明 | 可选值 | |------|------|------|--------| | status | 字符串 | 对话项状态 | completed, in_progress, incomplete | | role | 字符串 | 发送者角色 | user, assistant, system | | type | 字符串 | 对话项类型 | message, function_call, function_call_output | ### 内容类型参数表 | 参数 | 类型 | 说明 | 可选值 | |------|------|------|--------| | type | 字符串 | 内容类型 | text, audio, transcript | | format | 字符串 | 内容格式 | plain, markdown, html | | encoding | 字符串 | 编码方式 | utf-8, base64 | ### 响应状态参数表 | 参数 | 类型 | 说明 | 可选值 | |------|------|------|--------| | status | 字符串 | 响应状态 | completed, cancelled, failed, incomplete | | status_details | 对象 | 状态详情 | {"reason": "user_cancelled"} | | usage | 对象 | 使用统计 | {"total_tokens": 50, "input_tokens": 20, "output_tokens": 30} | ### 音频转写参数表 | 参数 | 类型 | 说明 | 示例值 | |------|------|------|--------| | enabled | 布尔值 | 是否启用转写 | true | | model | 字符串 | 转写模型 | whisper-1 | | language | 字符串 | 转写语言 | en, zh, auto | | prompt | 字符串 | 转写提示词 | "Transcript of a conversation" | ### 音频流参数表 | 参数 | 类型 | 说明 | 可选值 | |------|------|------|--------| | chunk_size | 整数 | 音频块大小(字节) | 1024, 2048, 4096 | | latency | 字符串 | 延迟模式 | low, balanced, high | | compression | 字符串 | 压缩方式 | none, opus, mp3 | ### WebRTC 配置参数表 | 参数 | 类型 | 说明 | 默认值 | |------|------|------|--------| | ice_servers | 数组 | ICE 服务器列表 | [{"urls": "stun:stun.l.google.com:19302"}] | | audio_constraints | 对象 | 音频约束 | {"echoCancellation": true} | | connection_timeout | 整数 | 连接超时(毫秒) | 30000 | # 图像（Image） # OpenAI 图像格式（Image） 官方文档 - [OpenAI Images](https://platform.openai.com/docs/api-reference/images) ## 📝 简介 给定文本提示和/或输入图片，模型将生成新的图片。OpenAI 提供多种强大的图像生成模型，可以根据自然语言描述创建、编辑和修改图像。目前支持的模型包括： | 模型 | 描述 | | --- | --- | | **DALL·E 系列** | 包括 DALL·E 2 和 DALL·E 3 两个版本，它们在图像质量、创意表现和精确度上都有显著差异 | | **GPT-Image-1** | OpenAI最新图片模型，支持多图片编辑功能，能够基于多个输入图像创建新的组合图像 | ## 💡 请求示例 ### 创建图片 ✅ ```bash # 基础图片生成 curl https://$Burncloud_API_BaseUrl/v1/images/generations \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $Burncloud_API_KEY" \ -d '{ "model": "dall-e-3", "prompt": "一只可爱的小海獭", "n": 1, "size": "1024x1024" }' # 高质量图片生成 curl https://$Burncloud_API_BaseUrl/v1/images/generations \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $Burncloud_API_KEY" \ -d '{ "model": "dall-e-3", "prompt": "一只可爱的小海獭", "quality": "hd", "style": "vivid", "size": "1024x1024" }' # 使用 base64 返回格式 curl https://$Burncloud_API_BaseUrl/v1/images/generations \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $Burncloud_API_KEY" \ -d '{ "model": "dall-e-3", "prompt": "一只可爱的小海獭", "response_format": "b64_json" }' ``` **响应示例:** ```json { "created": 1589478378, "data": [ { "url": "https://...", "revised_prompt": "一只可爱的小海獭在水中嬉戏,它有着圆圆的眼睛和毛茸茸的皮毛" } ] } ``` ### 编辑图片 ✅ ```bash # dall-e-2 图片编辑 curl https://$Burncloud_API_BaseUrl/v1/images/edits \ -H "Authorization: Bearer $Burncloud_API_KEY" \ -F image="@otter.png" \ -F mask="@mask.png" \ -F prompt="一只戴着贝雷帽的可爱小海獭" \ -F n=2 \ -F size="1024x1024" # gpt-image-1 多图片编辑示例 curl https://$Burncloud_API_BaseUrl/v1/images/edits \ -H "Authorization: Bearer $Burncloud_API_KEY" \ -F "model=gpt-image-1" \ -F "image[]=@body-lotion.png" \ -F "image[]=@bath-bomb.png" \ -F "image[]=@incense-kit.png" \ -F "image[]=@soap.png" \ -F "prompt=创建一个包含这四个物品的精美礼品篮" \ -F "quality=high" ``` **响应示例 (dall-e-2):** ```json { "created": 1589478378, "data": [ { "url": "https://..." }, { "url": "https://..." } ] } ``` **响应示例 (gpt-image-1):** ```json { "created": 1713833628, "data": [ { "b64_json": "..." } ], "usage": { "total_tokens": 100, "input_tokens": 50, "output_tokens": 50, "input_tokens_details": { "text_tokens": 10, "image_tokens": 40 } } } ``` ### 生成图片变体 ✅ ```bash curl https://$Burncloud_API_BaseUrl/v1/images/variations \ -H "Authorization: Bearer $Burncloud_API_KEY" \ -F image="@otter.png" \ -F n=2 \ -F size="1024x1024" ``` **响应示例:** ```json { "created": 1589478378, "data": [ { "url": "https://..." }, { "url": "https://..." } ] } ``` ## 📮 请求 ### 端点 #### 创建图片 ``` POST /v1/images/generations ``` 根据文本提示创建图片。 #### 编辑图片 ``` POST /v1/images/edits ``` 根据一个或多个原始图片和提示创建编辑或扩展的图片。此端点支持 dall-e-2 和 gpt-image-1 模型。 #### 生成变体 ``` POST /v1/images/variations ``` 创建给定图片的变体。 ### 鉴权方法 在请求头中包含以下内容进行 API 密钥认证： ``` Authorization: Bearer $Burncloud_API_KEY ``` 其中 `$OPENAI_API_KEY` 是您的 API 密钥。 ### 请求体参数 #### 创建图片 ##### `prompt` - 类型：字符串 - 必需：是 - 说明：期望生成图片的文本描述。 - dall-e-2 最大长度为 1000 字符 - dall-e-3 最大长度为 4000 字符 - 提示： - 使用具体和详细的描述 - 包含关键的视觉元素 - 指定期望的艺术风格 - 描述构图和视角 ##### `model` - 类型：字符串 - 必需：否 - 默认值：dall-e-2 - 说明：用于图像生成的模型。 ##### `n` - 类型：整数或 null - 必需：否 - 默认值：1 - 说明：要生成的图片数量。必须在 1-10 之间。dall-e-3 仅支持 n=1。 ##### `quality` - 类型：字符串 - 必需：否 - 默认值：standard - 说明：生成图片的质量。hd 选项会生成更细致和一致的图片。仅 dall-e-3 支持此参数。 ##### `response_format` - 类型：字符串或 null - 必需：否 - 默认值：url - 说明：返回生成图片的格式。必须是 url 或 b64_json 之一。URL 在生成后 60 分钟内有效。 ##### `size` - 类型：字符串或 null - 必需：否 - 默认值：1024x1024 - 说明：生成图片的尺寸。dall-e-2 必须是 256x256、512x512 或 1024x1024 之一。dall-e-3 必须是 1024x1024、1792x1024 或 1024x1792 之一。 ##### `style` - 类型：字符串或 null - 必需：否 - 默认值：vivid - 说明：生成图片的风格。必须是 vivid 或 natural 之一。vivid 倾向于生成超现实和戏剧性的图片，natural 倾向于生成更自然、不那么超现实的图片。仅 dall-e-3 支持此参数。 ##### `user` - 类型：字符串 - 必需：否 - 说明：代表最终用户的唯一标识符，可帮助 OpenAI 监控和检测滥用行为。 #### 编辑图片 ##### `image` - 类型：文件或文件数组 - 必需：是 - 说明：要编辑的图片。 - 对于 dall-e-2：必须是有效的 PNG 文件，小于 4MB，且为正方形。如果未提供 mask，图片必须具有透明度，这将用作蒙版。 - 对于 gpt-image-1：可以提供多个图片作为数组，每个图片应为 PNG、WEBP 或 JPG 文件，小于 25MB。 ##### `prompt` - 类型：字符串 - 必需：是 - 说明：期望生成图片的文本描述。 - dall-e-2 最大长度为 1000 字符 - gpt-image-1 最大长度为 32000 字符 ##### `mask` - 类型：文件 - 必需：否 - 说明：额外的图片，其完全透明区域（如 alpha 为零的区域）指示应该编辑的位置。如果提供了多个图片，mask 将应用于第一张图片。必须是有效的 PNG 文件，小于 4MB，且与 image 具有相同尺寸。 ##### `model` - 类型：字符串 - 必需：否 - 默认值：dall-e-2 - 说明：用于图像生成的模型。支持 dall-e-2 和 gpt-image-1。除非使用了 gpt-image-1 特有的参数，否则默认为 dall-e-2。 ##### `quality` - 类型：字符串或 null - 必需：否 - 默认值：auto - 说明：生成图片的质量。 - gpt-image-1 支持 high、medium 和 low - dall-e-2 仅支持 standard - 默认为 auto ##### `size` - 类型：字符串或 null - 必需：否 - 默认值：1024x1024 - 说明：生成图片的尺寸。 - gpt-image-1 必须是 1024x1024、1536x1024（横版）、1024x1536（竖版）或 auto（默认）之一 - dall-e-2 必须是 256x256、512x512 或 1024x1024 之一 其他参数与创建图片接口相同。 #### 生成变体 ##### `image` - 类型：文件 - 必需：是 - 说明：作为变体基础的图片。必须是有效的 PNG 文件，小于 4MB，且为正方形。 其他参数与创建图片接口相同。 ## 📥 响应 ### 成功响应 所有三个端点都返回包含图片对象列表的响应。 #### `created` - 类型：整数 - 说明：响应创建的时间戳 #### `data` - 类型：数组 - 说明：生成的图片对象列表 #### `usage`（仅适用于 gpt-image-1） - 类型：对象 - 说明：API 调用的令牌使用情况 - `total_tokens`：使用的总令牌数 - `input_tokens`：输入使用的令牌数 - `output_tokens`：输出使用的令牌数 - `input_tokens_details`：输入令牌的详细信息（文本令牌和图像令牌） ### 图片对象 #### `b64_json` - 类型：字符串 - 说明：如果 response_format 为 b64_json，则包含生成图片的 base64 编码 JSON #### `url` - 类型：字符串 - 说明：如果 response_format 为 url（默认），则包含生成图片的 URL #### `revised_prompt` - 类型：字符串 - 说明：如果提示有任何修改，则包含用于生成图片的修改后的提示 示例图片对象: ```json { "url": "https://...", "revised_prompt": "一只可爱的小海獭在水中嬉戏,它有着圆圆的眼睛和毛茸茸的皮毛" } ``` ## 🌟 最佳实践 ### Prompt 编写建议 1. 使用清晰具体的描述 2. 指定重要的视觉细节 3. 描述期望的艺术风格和氛围 4. 注意构图和视角的说明 ### 参数选择建议 1. 模型选择 - dall-e-3：适合需要高质量、精确细节的场景 - dall-e-2：适合快速原型或简单图像生成 2. 尺寸选择 - 1024x1024：通用场景的最佳选择 - 1792x1024/1024x1792：适合横版/竖版场景 - 较小尺寸：适合缩略图或快速预览 3. 质量和风格 - quality=hd：用于需要精细细节的图像 - style=vivid：适合创意和艺术效果 - style=natural：适合真实场景再现 ### gpt-image-2 参数 gpt-image-2 提供了丰富的参数，让你能精细地控制生成效果和成本。 1. 参数 类型 说明 示例/备注 - model string 必填。指定使用的模型，目前为 gpt-image-2。 "gpt-image-2" - prompt string 必填。描述你想要生成图像的文本。模型对多语言（尤其是中文）文字渲染能力很强。 "A serene cat..." - quality string 可选。生成质量，直接影响价格和生成速度。 "low" (草稿), "medium" (社交媒体), "high" (印刷品) - size string 可选。输出图像的尺寸。支持多种比例。 "1024x1024" (1:1), "1536x1024" (3:2), "1024x1792" (9:16) - n integer 可选。一次提示词生成的图像数量。范围是 1-8。 1 (默认), 4 - output_format string 可选。输出图像的格式。 "png" (支持透明背景), "jpeg", "webp" - background string 可选。设置背景是否为透明。 "auto", "transparent" (需配合 png 格式) ### 常见问题 1. 图片生成失败 - 检查 prompt 是否符合内容政策 - 确认文件格式和大小限制 - 验证 API 密钥权限 2. 结果与预期不符 - 优化 prompt 描述 - 调整质量和风格参数 - 考虑使用图片编辑或变体功能 # Midjourney 图像格式（Midjourney Proxy/Midjourney Proxy Plus） 请你注意 该接口 **非Midjourney官方的接口**，而是基于作者 **novicezk** 的开源项目 [**midjourney-proxy**](https://github.com/novicezk/midjourney-proxy) 实现的midjourney代理接口。 该项目分为两个版本，New API 都已经适配： - 开源版 [midjourney-proxy](https://github.com/novicezk/midjourney-proxy) - 付费版 [midjourney-proxy-plus](https://github.com/litter-coder/midjourney-proxy-plus) 这里非常感谢作者的贡献，让我们可以方便使用midjourney的强大功能，如果有时间，请给作者一个Star，如果有能力，建议支持作者的付费版本，该版本支持更多功能。 | 功能类别 | 开源版 | 付费版 | |---------|--------|--------| | **基础功能** | | | | Imagine指令及相关动作 | ✓ | ✓ | | 垫图支持 | ✓ | ✓ | | Blend(图片混合) | ✓ | ✓ | | Describe(图生文) | ✓ | ✓ | | 任务实时进度 | ✓ | ✓ | | 中文prompt翻译 | ✓ | ✓ | | prompt敏感词检测 | ✓ | ✓ | | user-token连接wss | ✓ | ✓ | | 多账号配置 | ✓ | ✓ | | **高级功能** | | | | Shorten(prompt分析) | ✗ | ✓ | | 焦点移动(Pan) | ✗ | ✓ | | 图片变焦(Zoom) | ✗ | ✓ | | 局部重绘(Vary Region) | ✗ | ✓ | | 关联按钮动作和Remix模式 | ✗ | ✓ | | 获取图片seed值 | ✗ | ✓ | | **账号管理** | | | | 账号池持久化 | ✗ | ✓ | | 多种存储支持(Redis/MySQL) | ✗ | ✓ | | 账号信息获取和设置 | ✗ | ✓ | | 任务取消功能 | ✗ | ✓ | | 内置管理后台 | ✗ | ✓ | | **智能特性** | | | | MJ V6.0支持 | ✗ | ✓ | | 账号状态自动监控 | ✗ | ✓ | | 模式自动切换 | ✗ | ✓ | | niji・journey Bot支持 | ✗ | ✓ | | InsightFace人脸服务 | ✗ | ✓ | | **安全性能** | | | | 动态配置支持 | ✗ | ✓ | | token掉线问题修复 | ✗ | ✓ | | 自动验证功能 | ✗ | ✓ | | 违禁词自动申诉 | ✗ | ✓ | ## 📝 简介 Midjourney是一个强大的图像生成和处理模型，可以根据自然语言描述创建、编辑和修改图像。通过提供不同的接口，可以实现各种图像生成和处理任务。 ## 🔄 流程示意图 [![Midjourney.webp](/uploads/images/gallery/2025-08/midjourney.webp)](/uploads/images/gallery/2025-08/midjourney.webp) ### 流程说明 1. **初始任务** - Imagine: 文本生成图片 - Blend: 多图混合 - Describe: 图片描述 - Swap Face: 人脸替换 2. **图片处理** - U1-U4: 放大操作 - V1-V4: 变体生成 - Pan: 图片平移 - Zoom: 图片缩放 3. **特殊流程** - Action + Modal: 需要弹窗确认的操作 - Action 直接执行: 不需要弹窗的操作 4. **任务管理** - 获取任务详情 - 获取图片 Seed - 上传至 Discord ## 💡 请求示例 ### 提交Imagine任务 ✅ ```bash curl --location --request POST 'https://$Burncloud_API_BaseUrl/mj/submit/imagine' \ --header 'Authorization: Bearer $Burncloud_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "botType": "MID_JOURNEY", "prompt": "Cat", "base64Array": [], "accountFilter": { "channelId": "", "instanceId": "", "modes": [], "remark": "", "remix": true, "remixAutoConsidered": true }, "notifyHook": "", "state": "" }' ``` **响应示例:** ```json { "code": 1, "description": "提交成功", "properties": {}, "result": 1320098173412546 } ``` ### 提交Blend任务 ✅ ```bash curl --location --request POST 'https://$Burncloud_API_BaseUrl/mj/submit/blend' \ --header 'Authorization: Bearer $Burncloud_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "botType": "MID_JOURNEY", "base64Array": [ "data:image/png;base64,xxx1", "data:image/png;base64,xxx2" ], "dimensions": "SQUARE", "accountFilter": { "channelId": "", "instanceId": "", "modes": [], "remark": "", "remix": true, "remixAutoConsidered": true }, "notifyHook": "", "state": "" }' ``` **响应示例:** ```json { "code": 1, "description": "提交成功", "properties": {}, "result": 1320098173412546 } ``` ### 提交Describe任务 ✅ ```bash curl --location --request POST 'https://$Burncloud_API_BaseUrl/mj/submit/describe' \ --header 'Authorization: Bearer $Burncloud_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "botType": "MID_JOURNEY", "base64": "data:image/png;base64,xxx", "accountFilter": { "channelId": "", "instanceId": "", "modes": [], "remark": "", "remix": true, "remixAutoConsidered": true }, "notifyHook": "", "state": "" }' ``` **响应示例:** ```json { "code": 1, "description": "提交成功", "properties": {}, "result": 1320098173412546 } ``` ### 提交Modal ✅ ```bash curl --location --request POST 'https://$Burncloud_API_BaseUrl/mj/submit/modal' \ --header 'Authorization: Bearer $Burncloud_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "maskBase64": "", "prompt": "", "taskId": "14001934816969359" }' ``` **响应示例:** ```json { "code": 1, "description": "提交成功", "properties": {}, "result": 1320098173412546 } ``` ### 提交swap_face任务 ✅ ```bash curl --location --request POST 'https://$Burncloud_API_BaseUrl/mj/insight-face/swap' \ --header 'Authorization: Bearer $Burncloud_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "sourceBase64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAkGBwgHBgkIBwgKCgkLDRYPDQwMDRsUFRAWIB0iIiAdHx8kKDQsJCYxJx8fLT0tMTU3Ojo6Iys/RDnYdriP1wsS81kwU8OVs/R3xu8s6bX7+zYnOH8coSqpmRSBjqerjcBlr2OB/lbAf/2Q==", "targetBase64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAkGBwgHBgkIBwgKCgkLDRYPDQwMDRsUFRAWIB0iIiAdHx8kKDQsJCYxJx8fLT0tMTU3Ojo6Iys/RD849k=" }' ``` **响应示例:** ```json { "code": 0, "description": "string", "result": "string" } ``` ### 执行Action动作 ✅ ```bash curl --location --request POST 'https://$Burncloud_API_BaseUrl/mj/submit/action' \ --header 'Authorization: Bearer $Burncloud_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "chooseSameChannel": true, "customId": "MJ::JOB::upsample::1::82c51c9d-bc33-4c07-a471-36c3dcb1a6f0", "taskId": "1728781324658687", "accountFilter": { "channelId": "", "instanceId": "", "modes": [], "remark": "", "remix": true, "remixAutoConsidered": true }, "notifyHook": "", "state": "" }' ``` **响应示例:** ```json { "code": 1, "description": "提交成功", "properties": {}, "result": 1320098173412546 } ``` ### 上传文件到discord ✅ ```bash curl --location --request POST 'https://$Burncloud_API_BaseUrl/mj/submit/upload-discord-images' \ --header 'Authorization: Bearer $Burncloud_API_KEY' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "base64Array": [], "filter": { "channelId": "", "instanceId": "", "remark": "" } }' ``` **响应示例:** ```json { "code": 0, "description": "string", "result": [ "string" ] } ``` ### 根据ID列表查询任务 ✅ ```bash curl --location --request POST 'https://$Burncloud_API_BaseUrl/mj/task/list-by-condition' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer $Burncloud_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "ids": [] }' ``` **响应示例:** ```json [ { "action": "IMAGINE", "buttons": [ { "customId": "string", "emoji": "string", "label": "string", "style": 0, "type": 0 } ], "description": "string", "failReason": "string", "finishTime": 0, "id": "string", "imageUrl": "string", "progress": "string", "prompt": "string", "promptEn": "string", "properties": {}, "startTime": 0, "state": "string", "status": "NOT_START", "submitTime": 0 } ] ``` ### 指定ID获取任务 ✅ ```bash curl --location --request GET 'https://$Burncloud_API_BaseUrl/mj/task/{id}/fetch' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer $Burncloud_API_KEY' \ --header 'Content-Type: application/json' ``` **响应示例:** ```json { "action": "IMAGINE", "buttons": [ { "customId": "string", "emoji": "string", "label": "string", "style": 0, "type": 0 } ], "description": "string", "failReason": "string", "finishTime": 0, "id": "string", "imageUrl": "string", "progress": "string", "prompt": "string", "promptEn": "string", "properties": {}, "startTime": 0, "state": "string", "status": "NOT_START", "submitTime": 0 } ``` ### 获取任务图片的seed ✅ ```bash curl --location --request GET 'https://$Burncloud_API_BaseUrl/mj/task/{id}/image-seed' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer $Burncloud_API_KEY' \ --header 'Content-Type: application/json' ``` **响应示例:** ```json { "code": 0, "description": "string", "result": "string" } ``` ## 📮 请求 ### 端点 #### 提交Imagine任务 ``` POST /mj/submit/imagine ``` 根据文本提示创建图片。 #### 提交Blend任务 ``` POST /mj/submit/blend ``` 根据多个输入图片融合生成新图片。 #### 提交Describe任务 ``` POST /mj/submit/describe ``` 根据输入图片生成文字描述。 #### 提交Modal ``` POST /mj/submit/modal ``` 提交模态信息,用于调整图片生成细节。 #### 提交swap_face任务 ``` POST /mj/insight-face/swap ``` 根据源图片和目标图片进行人脸交换。 #### 执行Action动作 ``` POST /mj/submit/action ``` 对已生成的图片进行后续操作,如放大、调整等。 #### 上传文件到discord ``` POST /mj/submit/upload-discord-images ``` 将图片上传到discord平台。 #### 根据ID列表查询任务 ``` POST /mj/task/list-by-condition ``` 根据指定的任务ID列表查询任务详情。 #### 指定ID获取任务 ``` GET /mj/task/{id}/fetch ``` 根据任务ID获取任务详情。 #### 获取任务图片的seed ``` GET /mj/task/{id}/image-seed ``` 获取指定任务生成图片的seed值。 ### 鉴权方法 在请求头中包含以下内容进行 API 密钥认证： ``` Authorization: Bearer $Burncloud_API_KEY$OPENAI_API_KEY ``` 其中 `$OPENAI_API_KEY` 是您的 API 密钥。 ### 请求体参数 #### 提交 Imagine 任务 ##### `botType` - 类型：枚举字符串 - 必需：否 - 默认值：MID_JOURNEY - 可选值： - `MID_JOURNEY`: Midjourney 模型 - `NIJI_JOURNEY`: Niji Journey 模型 - 说明：选择使用的 bot 类型 ##### `prompt` - 类型：字符串 - 必需：是 - 说明：图像生成的文本提示词 - 提示： - 使用清晰具体的描述 - 可以包含艺术风格、构图等细节 - 支持英文和中文输入 ##### `base64Array` - 类型：字符串数组 - 必需：否 - 说明：垫图的 base64 编码数组 - 格式：每个元素应为完整的 base64 图片字符串，包含 MIME 类型前缀 ##### `accountFilter` - 类型：对象 - 必需：否 - 属性： - `channelId`: 频道 ID - `instanceId`: 账号实例 ID - `modes`: 账号模式数组，可选值：RELAX、FAST、TURBO - `remark`: 备注包含的内容 - `remix`: 账号是否支持 remix - `remixAutoConsidered`: remix 自动提交设置 ##### `notifyHook` - 类型：字符串 - 必需：否 - 说明：任务完成后的回调地址，为空时使用全局 notifyHook ##### `state` - 类型：字符串 - 必需：否 - 说明：自定义状态参数，可用于跟踪请求 #### 提交 Blend 任务 ##### `base64Array` - 类型：字符串数组 - 必需：是 - 说明：要混合的图片 base64 编码数组 - 格式：必须包含 2-5 张图片的 base64 字符串 ##### `dimensions` - 类型：枚举字符串 - 必需：否 - 可选值： - `PORTRAIT`: 2:3 比例 - `SQUARE`: 1:1 比例 - `LANDSCAPE`: 3:2 比例 - 说明：输出图片的宽高比设置 #### 提交 Describe 任务 ##### `base64` - 类型：字符串 - 必需：是 - 说明：需要描述的图片的 base64 编码 - 格式：完整的 base64 字符串，包含 MIME 类型前缀 #### 提交 Modal 任务 ##### `maskBase64` - 类型：字符串 - 必需：否 - 说明：局部重绘的蒙版图片 base64 编码 ##### `prompt` - 类型：字符串 - 必需：否 - 说明：重绘区域的文本提示词 ##### `taskId` - 类型：字符串 - 必需：是 - 说明：原始任务的 ID #### 提交 Swap Face 任务 ##### `sourceBase64` - 类型：字符串 - 必需：是 - 说明：人脸源图片的 base64 编码 - 要求：图片必须包含清晰的人脸 ##### `targetBase64` - 类型：字符串 - 必需：是 - 说明：目标图片的 base64 编码 - 要求：图片必须包含要替换的人脸 #### 执行 Action 动作 ##### `chooseSameChannel` - 类型：布尔值 - 必需：否 - 默认值：false - 说明：是否选择同一频道下的账号 ##### `customId` - 类型：字符串 - 必需：是 - 说明：动作标识符 - 格式：特定格式的字符串，如 "MJ::JOB::upsample::1::xxx" ##### `taskId` - 类型：字符串 - 必需：是 - 说明：要执行动作的任务 ID #### 上传文件到 Discord ##### `base64Array` - 类型：字符串数组 - 必需：是 - 说明：要上传的图片 base64 编码数组 ##### `filter` - 类型：对象 - 必需：否 - 属性： - `channelId`: 目标频道 ID - `instanceId`: 账号实例 ID - `remark`: 备注信息 #### 根据 ID 列表查询任务 ##### `ids` - 类型：字符串数组 - 必需：是 - 说明：要查询的任务 ID 列表 ### 通用响应格式 所有接口都返回相似的响应结构： ##### `code` - 类型：整数 - 说明：状态码 | 状态码 | 说明 | |--------|------| | 1 | 提交成功 | | 22 | 任务排队中 | | 21 | 参数错误 | | 23 | 系统错误 | | 24 | 账号不可用 | | 25 | 余额不足 | ##### `description` - 类型：字符串 - 说明：响应描述信息 ##### `properties` - 类型：对象 - 说明：扩展属性 ##### `result` - 类型：字符串或数组 - 说明：返回结果，可能是任务 ID 或其他数据 ## 📥 响应 ### 成功响应 #### `action` - 类型：枚举字符串 - 说明：任务类型 | 字符串值 | 说明 | |--------|------| | `IMAGINE` | 创建图片 | | `UPSCALE` | 放大图片 | | `VARIATION` | 变体生成 | | `ZOOM` | 缩放图片 | | `PAN` | 平移图片 | | `DESCRIBE` | 图片描述 | | `BLEND` | 图片混合 | | `SHORTEN` | 缩短提示词 | | `SWAP_FACE` | 人脸替换 | #### `buttons` - 类型：对象数组 - 说明：可执行的操作按钮 | 数组包含属性 | 说明 | |--------|------| | `customId` | 动作标识 | | `emoji` | 按钮图标 | | `label` | 按钮文本 | | `style` | 样式(2=Primary, 3=Green) | | `type` | 系统内部使用的类型 | #### `description` - 类型：字符串 - 说明：任务描述信息 #### `failReason` - 类型：字符串 - 说明：任务失败原因 #### `finishTime` - 类型：整数 - 说明：任务完成时间戳 #### `id` - 类型：字符串 - 说明：任务唯一标识符 #### `imageUrl` - 类型：字符串 - 说明：生成图片的URL #### `progress` - 类型：字符串 - 说明：任务进度信息 #### `prompt` - 类型：字符串 - 说明：原始提示词 #### `promptEn` - 类型：字符串 - 说明：英文提示词 #### `status` - 类型：枚举字符串 - 说明：任务状态 | 字符串值 | 说明 | |--------|------| | `NOT_START` | 未开始 | | `SUBMITTED` | 已提交 | | `MODAL` | 模态操作中 | | `IN_PROGRESS` | 进行中 | | `FAILURE` | 失败 | | `SUCCESS` | 成功 | | `CANCEL` | 已取消 | #### `submitTime` - 类型：整数 - 说明：任务提交时间戳 #### `startTime` - 类型：整数 - 说明：任务开始执行时间戳 ### 错误响应 当请求出现问题时，API 将返回错误响应： #### HTTP 状态码 - `400 Bad Request`: 请求参数无效 - `401 Unauthorized`: API 密钥无效或未提供 - `403 Forbidden`: 权限不足 - `404 Not Found`: 资源不存在 - `429 Too Many Requests`: 请求频率超限 - `500 Internal Server Error`: 服务器内部错误 #### 错误响应格式 ```json { "code": <错误码>, "description": "错误描述信息", "result": null } ``` ## 💡 最佳实践 ### Prompt 编写建议 1. 使用清晰简洁的语言描述期望的图像内容 2. 可以参考Midjourney支持的各种参数来控制图片风格 3. 适当使用否定描述以排除不需要的元素 4. 可以通过图片URL作为参考来指导生成 ### 图片生成流程 1. 提交Imagine任务,获得初步图片 2. 必要时通过Blend、Modal等任务进一步优化 3. 执行Action动作进行图片微调 4. 将满意的结果图片上传保存 ### 图片格式要求 1. 支持的图片格式： - JPEG/JPG - PNG - GIF (静态) - WEBP 2. 图片大小限制： - 文件大小：最大 4MB - 分辨率：建议 1024x1024 或更高 - 宽高比：支持 1:1、2:3、3:2 ### 性能优化建议 1. Base64 编码： - 使用标准 Base64 编码格式 - 包含正确的 MIME 类型前缀 - 压缩图片以减少数据传输 2. 任务处理： - 使用 webhook 接收任务完成通知 - 合理设置重试策略 - 建议使用异步处理方式 ### 错误处理 - 实现请求重试机制 - 添加错误日志记录 - 设置合理的超时时间 # gemini-3 图片生成API [含4K] #### 2K图片 / 4K图片 请求 ~~~ https://ai.burncloud.com/v1beta/models/gemini-3-pro-image-preview:generateContent?key=sk-xxxxxxxxxxxxxxxxxxx' { "contents": [ { "role": "user", "parts": [ { "text": "画条狗" } ] } ] , "generationConfig": { "temperature": 1 ,"maxOutputTokens": 32768 ,"responseModalities": ["TEXT", "IMAGE"] ,"topP": 0.95 ,"imageConfig": { "aspectRatio": "1:1" ,"imageSize": "4K" ,"imageOutputOptions": { "mimeType": "image/png" } ,"personGeneration": "ALLOW_ALL" } } } ~~~ ### 参考图生图，改图，还是沿用上面的代码，只是修改以下部分content部分： ~~~ { "contents": [ { "role": "user", "parts": [ { "text": "画条狗" }, { "fileData": { "mimeType": "image/jpeg", "fileUri": "https://XXXXXX.com/i/2025/01/06/677bbb1f2411d.webp" } } ] } ] ~~~ ### 获取图片，请看返回结果，拿图片的base64 # 音频（Audio） # OpenAI 音频格式 官方文档 - [OpenAI Audio](https://platform.openai.com/docs/api-reference/audio) ## 📝 简介 OpenAI 音频 API 提供了三个主要功能: 1. 文本转语音(TTS) - 将文本转换为自然的语音 2. 语音转文本(STT) - 将音频转录为文本 3. 音频翻译 - 将非英语音频翻译成英语文本 ## 💡 请求示例 ### 文本转语音 ✅ ```bash curl https://$Burncloud_API_BaseUrl/v1/audio/speech \ -H "Authorization: Bearer $Burncloud_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "tts-1", "input": "你好,世界!", "voice": "alloy" }' \ --output speech.mp3 ``` ### 语音转文本 ✅ ```bash curl https://$Burncloud_API_BaseUrl/v1/audio/transcriptions \ -H "Authorization: Bearer $Burncloud_API_KEY" \ -H "Content-Type: multipart/form-data" \ -F file="@/path/to/file/audio.mp3" \ -F model="whisper-1" ``` **响应示例:** ```json { "text": "你好,世界!" } ``` ### 音频翻译 ✅ ```bash curl https://$Burncloud_API_BaseUrl/v1/audio/translations \ -H "Authorization: Bearer $Burncloud_API_KEY" \ -H "Content-Type: multipart/form-data" \ -F file="@/path/to/file/chinese.mp3" \ -F model="whisper-1" ``` **响应示例:** ```json { "text": "Hello, world!" } ``` ## 📮 请求 ### 端点 #### 文本转语音 ``` POST /v1/audio/speech ``` 将文本转换为语音。 #### 语音转文本 ``` POST /v1/audio/transcriptions ``` 将音频转录为输入语言的文本。 #### 音频翻译 ``` POST /v1/audio/translations ``` 将音频翻译为英语文本。 ### 鉴权方法 在请求头中包含以下内容进行 API 密钥认证： ``` Authorization: Bearer $Burncloud_API_KEY ``` 其中 `$Burncloud_API_KEY` 是您的 API 密钥。 ### 请求体参数 #### 文本转语音 ##### `model` - 类型：字符串 - 必需：是 - 可选值：tts-1, tts-1-hd - 说明：要使用的 TTS 模型 ##### `input` - 类型：字符串 - 必需：是 - 最大长度：4096 字符 - 说明：要转换为语音的文本 ##### `voice` - 类型：字符串 - 必需：是 - 可选值：alloy, echo, fable, onyx, nova, shimmer - 说明：生成语音时使用的声音 ##### `response_format` - 类型：字符串 - 必需：否 - 默认值：mp3 - 可选值：mp3, opus, aac, flac, wav, pcm - 说明：音频输出格式 ##### `speed` - 类型：数字 - 必需：否 - 默认值：1.0 - 范围：0.25 - 4.0 - 说明：生成语音的速度 #### 语音转文本 ##### `file` - 类型：文件 - 必需：是 - 支持格式：flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm - 说明：要转录的音频文件 ##### `model` - 类型：字符串 - 必需：是 - 当前仅支持：whisper-1 - 说明：要使用的模型 ID ##### `language` - 类型：字符串 - 必需：否 - 格式：ISO-639-1 (如 "en") - 说明：音频的语言,提供可提高准确性 ##### `prompt` - 类型：字符串 - 必需：否 - 说明：用于指导模型风格或继续前一段音频的文本 ##### `response_format` - 类型：字符串 - 必需：否 - 默认值：json - 可选值：json, text, srt, verbose_json, vtt - 说明：输出格式 ##### `temperature` - 类型：数字 - 必需：否 - 默认值：0 - 范围：0 - 1 - 说明：采样温度,较高的值使输出更随机 ##### `timestamp_granularities` - 类型：数组 - 必需：否 - 默认值：segment - 可选值：word, segment - 说明：转录的时间戳粒度 #### 音频翻译 ##### `file` - 类型：文件 - 必需：是 - 支持格式：flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm - 说明：要翻译的音频文件 ##### `model` - 类型：字符串 - 必需：是 - 当前仅支持：whisper-1 - 说明：要使用的模型 ID ##### `prompt` - 类型：字符串 - 必需：否 - 说明：用于指导模型风格的英文文本 ##### `response_format` - 类型：字符串 - 必需：否 - 默认值：json - 可选值：json, text, srt, verbose_json, vtt - 说明：输出格式 ##### `temperature` - 类型：数字 - 必需：否 - 默认值：0 - 范围：0 - 1 - 说明：采样温度,较高的值使输出更随机 ## 📥 响应 ### 成功响应 #### 文本转语音 返回二进制音频文件内容。 #### 语音转文本 ##### 基础 JSON 格式 ```json { "text": "转录的文本内容" } ``` ##### 详细 JSON 格式 ```json { "task": "transcribe", "language": "english", "duration": 8.47, "text": "完整的转录文本", "segments": [ { "id": 0, "seek": 0, "start": 0.0, "end": 3.32, "text": "分段的转录文本", "tokens": [50364, 440, 7534], "temperature": 0.0, "avg_logprob": -0.286, "compression_ratio": 1.236, "no_speech_prob": 0.009 } ] } ``` #### 音频翻译 ```json { "text": "翻译后的英文文本" } ``` ### 错误响应 当请求出现问题时，API 将返回一个错误响应对象，HTTP 状态码在 4XX-5XX 范围内。 #### 常见错误状态码 - `400 Bad Request`: 请求参数无效 - `401 Unauthorized`: API 密钥无效或未提供 - `429 Too Many Requests`: 超出 API 调用限制 - `500 Internal Server Error`: 服务器内部错误 错误响应示例: ```json { "error": { "message": "文件格式不支持", "type": "invalid_request_error", "param": "file", "code": "invalid_file_format" } } ``` # 音乐（Music） # Suno 音乐格式（Music） 请你注意 该接口 **非Suno官方的接口**，而是基于作者 **柏拉图** 的开源项目 [**Suno-API**](https://github.com/Suno-API/Suno-API) 实现的Suno代理接口。 这里非常感谢作者的贡献，让我们可以方便使用Suno的强大功能，如果有时间，请给作者一个Star。 ## 📝 简介 Suno Music API 提供了一系列音乐生成和处理的功能，包括: - 根据提示生成歌曲（灵感模式、自定义模式） - 续写已有歌曲 - 拼接多个音频片段 - 生成歌词 - 上传音频 通过 API 可以方便地将 AI 音乐生成能力集成到你的应用中。 ## 💡 请求示例 ### 生成歌曲 ✅ ```bash curl --location 'https://$Burncloud_API_BaseUrl/suno/submit/music' \ --header 'Authorization: Bearer $Burncloud_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "prompt":"[Verse]\nWalking down the streets\nBeneath the city lights\nNeon signs flickering\nLighting up the night\nHeart beating faster\nLike a drum in my chest\nI'\''m alive in this moment\nFeeling so blessed\n\nStilettos on the pavement\nStepping with grace\nSurrounded by the people\nMoving at their own pace\nThe rhythm of the city\nIt pulses in my veins\nLost in the energy\nAs my worries drain\n\n[Verse 2]\nConcrete jungle shining\nWith its dazzling glow\nEvery corner hiding secrets that only locals know\nA symphony of chaos\nBut it'\''s music to my ears\nThe hustle and the bustle\nWiping away my fears", "tags":"emotional punk", "mv":"chirp-v4", "title":"City Lights" }' ``` **响应示例:** ```json { "code":"success", "message":"", "data":"736a6f88-bd29-4b1e-b110-37132a5325ac" } ``` ### 生成歌词 ✅ ```bash curl --location 'https://$Burncloud_API_BaseUrl/suno/submit/lyrics' \ --header 'Authorization: Bearer $Burncloud_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "prompt":"dance" }' ``` **响应示例:** ```json { "code":"success", "message":"", "data":"736a6f88-bd29-4b1e-b110-37132a5325ac" } ``` ### 上传音频 ❌ ```bash curl --location 'https://$Burncloud_API_BaseUrl/suno/uploads/audio-url' \ --header 'Authorization: Bearer $Burncloud_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "url":"http://cdnimg.example.com/ai/2024-06-18/d416d9c3c34eb22c7d8c094831d8dbd0.mp3" }' ``` **响应示例:** ```json { "code":"success", "message":"", "data":"736a6f88-bd29-4b1e-b110-37132a5325ac" } ``` ### 歌曲拼接 ❌ ```bash curl --location 'https://$Burncloud_API_BaseUrl/suno/submit/concat' \ --header 'Authorization: Bearer $Burncloud_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "clip_id":"extend 后的 歌曲ID", "is_infill": false }' ``` **响应示例:** ```json { "code":"success", "message":"", "data":"736a6f88-bd29-4b1e-b110-37132a5325ac" } ``` ### 查询任务状态 ✅ #### 批量查询 ```bash curl --location 'https://$Burncloud_API_BaseUrl/suno/fetch' \ --header 'Authorization: Bearer $Burncloud_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "ids":["task_id"], "action":"MUSIC" }' ``` **响应示例:** ```json { "code":"success", "message":"", "data":[ { "task_id":"346c5d10-a4a1-4f49-a851-66a7dae6cfaf", "notify_hook":"", "action":"MUSIC", "status":"IN_PROGRESS", "fail_reason":"", "submit_time":1716191749, "start_time":1716191786, "finish_time":0, "progress":"0%", "data":[ { "id":"e9893d04-6a63-4007-8473-64b706eca4d1", "title":"Electric Dance Party", "status":"streaming", "metadata":{ "tags":"club banger high-energy edm", "prompt":"略", "duration":null, "error_type":null, "error_message":null, "audio_prompt_id":null, "gpt_description_prompt":"miku dance" }, "audio_url":"https://audiopipe.suno.ai/?item_id=e9893d04-6a63-4007-8473-64b706eca4d1", "image_url":"https://cdn1.suno.ai/image_e9893d04-6a63-4007-8473-64b706eca4d1.png", "video_url":"", "model_name":"chirp-v3", "image_large_url":"https://cdn1.suno.ai/image_large_e9893d04-6a63-4007-8473-64b706eca4d1.png", "major_model_version":"v3" } ] } ] } ``` #### 单个查询 ```bash curl --location 'https://$Burncloud_API_BaseUrl/suno/fetch/{{task_id}}' \ --header 'Authorization: Bearer $Burncloud_API_KEY' ``` **响应示例:** ```json { "code":"success", "message":"", "data":{ "task_id":"f4a94d75-087b-4bb1-bd45-53ba293faf96", "notify_hook":"", "action":"LYRICS", "status":"SUCCESS", "fail_reason":"", "submit_time":1716192124, "start_time":1716192124, "finish_time":1716192124, "progress":"100%", "data":{ "id":"f4a94d75-087b-4bb1-bd45-53ba293faf96", "text":"略", "title":"Electric Fantasy", "status":"complete" } } } ``` ## 📮 请求 所有请求都需在请求头中包含认证信息: ``` Authorization: Bearer $Burncloud_API_KEY ``` ### 端点 #### 生成歌曲 ``` POST /suno/submit/music ``` 生成新的歌曲,支持灵感模式、自定义模式、续写。 #### 生成歌词 ``` POST /suno/submit/lyrics ``` 根据提示生成歌词。 #### 上传音频 ``` POST /suno/uploads/audio-url ``` 上传音频文件。 #### 歌曲拼接 ``` POST /suno/submit/concat ``` 将多个音频片段拼接为一首完整的歌曲。 #### 批量查询任务状态 ``` POST /suno/fetch ``` 批量获取多个任务的状态和结果。 #### 查询单个任务状态 ``` GET /suno/fetch/{{task_id}} ``` 查询单个任务的状态和结果。 ### 请求体参数 #### 生成歌曲 ##### `prompt` - 类型:String - 必需:灵感模式无需,自定义模式必需 - 说明:歌词内容,在自定义模式下需提供 ##### `mv` - 类型:String - 必需:否 - 说明:模型版本,可选值:chirp-v3-0、chirp-v3-5,默认为 chirp-v3-0 ##### `title` - 类型:String - 必需:灵感模式无需,自定义模式必需 - 说明:歌曲标题,在自定义模式下需提供 ##### `tags` - 类型:String - 必需:灵感模式无需,自定义模式必需 - 说明:歌曲风格标签,使用逗号分隔,在自定义模式下需提供 ##### `make_instrumental` - 类型:Boolean - 必需:否 - 说明:是否生成纯音乐,true 为生成纯音乐 ##### `task_id` - 类型:String - 必需:续写时必需 - 说明:要续写的歌曲的任务 ID ##### `continue_at` - 类型:Float - 必需:续写时必需 - 说明:从歌曲的第几秒开始续写 ##### `continue_clip_id` - 类型:String - 必需:续写时必需 - 说明:要续写的歌曲的 clip ID ##### `gpt_description_prompt` - 类型:String - 必需:灵感模式必需,其他模式无需 - 说明:灵感来源的文字描述 ##### `notify_hook` - 类型:String - 必需:否 - 说明:歌曲生成完成的回调通知地址 #### 生成歌词 ##### `prompt` - 类型:String - 必需:是 - 说明:歌词的主题或关键词 ##### `notify_hook` - 类型:String - 必需:否 - 说明:歌词生成完成的回调通知地址 #### 上传音频 ##### `url` - 类型:String - 必需:是 - 说明:要上传的音频文件的 URL 地址 #### 歌曲拼接 ##### `clip_id` - 类型:String - 必需:是 - 说明:要拼接的歌曲片段的 ID ##### `is_infill` - 类型:Boolean - 必需:否 - 说明:是否为填充模式 #### 任务查询 ##### `ids` - 类型:String[] - 必需:是 - 说明:要查询的任务 ID 列表 ##### `action` - 类型:String - 必需:否 - 说明:任务类型,可选值:MUSIC、LYRICS ## 📥 响应 所有接口均返回统一的 JSON 格式响应: ```json { "code":"success", "message":"", "data":"{{RESULT}}" } ``` ### 成功响应 #### 基础响应字段 ##### `code` - 类型:String - 说明:请求状态,success 为成功 ##### `message` - 类型:String - 说明:请求失败时的错误信息 ##### `data` - 类型:根据不同接口而异 - 说明:请求成功时的返回数据 - 生成歌曲、歌词、上传音频、歌曲拼接接口:返回任务 ID 字符串 - 任务查询接口:返回任务对象或任务对象数组 #### 任务相关对象 ##### 任务对象 ###### `task_id` - 类型:String - 说明:任务 ID ###### `notify_hook` - 类型:String - 说明:任务完成后的回调通知地址 ###### `action` - 类型:String - 说明:任务类型,可选值:MUSIC、LYRICS ###### `status` - 类型:String - 说明:任务状态,可选值:IN_PROGRESS、SUCCESS、FAIL ###### `fail_reason` - 类型:String - 说明:任务失败原因 ###### `submit_time` - 类型:Integer - 说明:任务提交时间戳 ###### `start_time` - 类型:Integer - 说明:任务开始时间戳 ###### `finish_time` - 类型:Integer - 说明:任务结束时间戳 ###### `progress` - 类型:String - 说明:任务进度百分比 ###### `data` - 类型:根据任务类型不同而异 - 说明: - 音乐生成任务:歌曲对象数组 - 歌词生成任务:歌词对象 ##### 歌曲对象 ###### `id` - 类型:String - 说明:歌曲 ID ###### `title` - 类型:String - 说明:歌曲标题 ###### `status` - 类型:String - 说明:歌曲状态 ###### `metadata` - 类型:Object - 说明:歌曲元数据 - tags:歌曲风格标签 - prompt:生成歌曲使用的歌词 - duration:歌曲时长 - error_type:错误类型 - error_message:错误信息 - audio_prompt_id:音频 prompt ID - gpt_description_prompt:灵感来源描述 ###### `audio_url` - 类型:String - 说明:歌曲音频的 URL 地址 ###### `image_url` - 类型:String - 说明:歌曲封面图的 URL 地址 ###### `video_url` - 类型:String - 说明:歌曲视频的 URL 地址 ###### `model_name` - 类型:String - 说明:生成歌曲使用的模型名称 ###### `major_model_version` - 类型:String - 说明:模型主版本号 ##### 歌词对象 ###### `id` - 类型:String - 说明:歌词 ID ###### `text` - 类型:String - 说明:歌词内容 ###### `title` - 类型:String - 说明:歌词标题 ###### `status` - 类型:String - 说明:歌词状态 ## 🌟 最佳实践 1. 提供尽量详细 、具体的歌曲或歌词生成提示,避免过于笼统或抽象 2. 查询任务状态时,轮询间隔建议为 2-5 秒,避免过于频繁 3. 灵感模式仅需提供 gpt_description_prompt 参数,API 会自动生成歌词、标题、标签等 4. 自定义模式需要提供 prompt、title、tags 参数,可以对歌曲有更多控制 5. 尽量使用最新版本的模型(如 chirp-v4),效果会更好 6. 使用回调通知功能(notify_hook 参数)可以降低轮询频率,提高效率 7. 音乐续写、拼接功能可以在原有音乐基础上,生成更加丰富、完整的作品 8. 注意处理可能出现的异常和错误,如网络超时、参数校验失败等 # 视频（Video） # 生成视频 调用视频生成接口生成视频，支持多种视频生成服务： - **可灵AI (Kling)**: [API文档](https://app.klingai.com/cn/dev/document-api/apiReference/commonInfo) - **即梦 (Jimeng)**: [API文档](https://www.volcengine.com/docs/85621/1538636) ## API 端点 ``` POST /v1/video/generations ``` ## 请求头 | 参数 | 类型 | 必填 | 描述 | |------|------|------|------| | Authorization | string | 是 | 用户认证令牌 (Bearer: sk-xxxx) | | Content-Type | string | 是 | application/json | ## 请求参数 | 参数 | 类型 | 必填 | 描述 | |------|------|------|------| | model | string | 是 | 模型/风格ID | | prompt | string | 是 | 文本提示词 | | duration | number | 否 | 视频时长（秒） | | fps | integer | 否 | 视频帧率 | | height | integer | 否 | 视频高度 | | width | integer | 否 | 视频宽度 | | image | string | 否 | 图片输入（URL/Base64） | | metadata | object | 否 | 供应商特定/自定义参数（如 negative_prompt, style, quality_level 等） | | n | integer | 否 | 生成视频数量 | | response_format | string | 否 | 响应格式 | | seed | integer | 否 | 随机种子 | | user | string | 否 | 用户标识符 | ## 请求示例 ### 可灵AI 示例 ```bash curl https://$Burncloud_API_BaseUrl/v1/video/generations \ --request POST \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "model": "kling-v1", "prompt": "一个穿着宇航服的宇航员在月球上行走, 高品质, 电影级", "size": "1920x1080", "image": "https://h2.inkwai.com/bs2/upload-ylab-stunt/se/ai_portal_queue_mmu_image_upscale_aiweb/3214b798-e1b4-4b00-b7af-72b5b0417420_raw_image_0.jpg", "duration": 5, "metadata": { "seed": 20231234, "negative_prompt": "模糊", "image_tail": "https://h1.inkwai.com/bs2/upload-ylab-stunt/1fa0ac67d8ce6cd55b50d68b967b3a59.png" } }' ``` ### 即梦AI 示例 ```bash curl https://$Burncloud_API_BaseUrl/v1/video/generations \ --request POST \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "model": "jimeng_vgfm_t2v_l20", "prompt": "一个穿着宇航服的宇航员在月球上行走", "image": "https://h2.inkwai.com/bs2/upload-ylab-stunt/se/ai_portal_queue_mmu_image_upscale_aiweb/3214b798-e1b4-4b00-b7af-72b5b0417420_raw_image_0.jpg", "metadata": { "req_key": "jimeng_vgfm_i2v_l20", "image_urls": [ "https://h2.inkwai.com/bs2/upload-ylab-stunt/se/ai_portal_queue_mmu_image_upscale_aiweb/3214b798-e1b4-4b00-b7af-72b5b0417420_raw_image_0.jpg" ], "aspect_ratio": "16:9" } }' ``` ### Vidu 渠道示例 ```bash curl https://$Burncloud_API_BaseUrl/v1/video/generations \ --request POST \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "model": "viduq1", "prompt": "一个穿着宇航服的宇航员在月球上行走, 高品质, 电影级", "size": "1920x1080", "image": "https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/image2video.png", "duration": 5, "metadata": { "duration": 5, "seed": 0, "resolution": "1080p", "movement_amplitude": "auto", "bgm": false, "payload": "", "callback_url": "https://your-callback-url.com/webhook" } }' ``` ## 响应格式 ### 错误响应 #### 400 - 请求参数错误 ```json { "code": null, "message": "string", "param": "string", "type": "string" } ``` #### 401 - 未授权 ```json { "code": null, "message": "string", "param": "string", "type": "string" } ``` #### 403 - 无权限 ```json { "code": null, "message": "string", "param": "string", "type": "string" } ``` #### 500 - 服务器内部错误 ```json { "code": null, "message": "string", "param": "string", "type": "string" } ``` # 查询视频 根据任务ID查询视频生成任务的状态和结果 ## API 端点 ``` GET /v1/video/generations/{task_id} ``` ## 路径参数 | 参数 | 类型 | 必填 | 描述 | |------|------|------|------| | task_id | string | 是 | 任务ID | ## 请求示例 ```bash curl 'https://$Burncloud_API_BaseUrl/v1/video/generations/{task_id}' ``` ## 响应格式 ### 200 - 成功响应 ```json { "error": null, "format": "mp4", "metadata": { "duration": 5, "fps": 30, "height": 512, "seed": 20231234, "width": 512 }, "status": "succeeded", "task_id": "abcd1234efgh", "url": "string" } ``` ### 响应字段说明 | 字段 | 类型 | 描述 | |------|------|------| | task_id | string | 任务ID | | status | string | 任务状态（processing: 处理中, succeeded: 成功, failed: 失败） | | format | string | 视频格式 | | url | string | 视频资源URL（成功时） | | metadata | object | 结果元数据 | | error | object | 错误信息（成功时为null） | ### 错误响应 #### 400 - 请求参数错误 ```json { "code": null, "message": "string", "param": "string", "type": "string" } ``` #### 401 - 未授权 ```json { "code": null, "message": "string", "param": "string", "type": "string" } ``` #### 403 - 无权限 ```json { "code": null, "message": "string", "param": "string", "type": "string" } ``` #### 500 - 服务器内部错误 ```json { "code": null, "message": "string", "param": "string", "type": "string" } ``` # OpenAI 视频 sora视频 # OpenAI 视频格式 API 文档 ## 目录 - [概述](#概述) - [生成视频](#生成视频) - [查询视频](#查询视频) - [获取视频任务状态](#获取视频任务状态) - [获取视频内容](#获取视频内容) - [错误响应](#错误响应) ## 概述 调用OpenAI视频生成接口生成视频，支持 Sora 等模型，也支持使用 OpenAI 视频格式调用可灵，即梦和 vidu。 ## 生成视频 ### API 端点 ``` POST /v1/videos ``` ### 请求头 | 参数 | 类型 | 必填 | 描述 | |------|------|------|------| | Authorization | string | 是 | 用户认证令牌 (Bearer: sk-xxxx) | | Content-Type | string | 是 | multipart/form-data | ### 请求参数 | 参数 | 类型 | 必填 | 描述 | |------|------|------|------| | prompt | string | 是 | 描述要生成视频的文本提示词 | | model | string | 否 | 视频生成模型，默认为 sora-2 | | seconds | string | 否 | 视频时长（秒），默认为 4 秒 | | size | string | 否 | 输出分辨率，格式为宽度x高度，默认为 720x1280 | | input_reference | file | 否 | 可选图片参考，用于指导生成 | ### 请求示例 ```bash curl https://ai.burncloud.com/v1/videos \ -H "Authorization: Bearer sk-xxxx" \ -F "model=sora-2" \ -F "prompt=A calico cat playing a piano on stage" \ -F "size=1280x720" \ -F "seconds=8" ``` ### 响应格式 #### 200 - 成功响应 ```json { "id": "video_123", "object": "video", "model": "sora-2", "status": "queued", "progress": 0, "created_at": 1712697600, "size": "1024x1808", "seconds": "8", "quality": "standard" } ``` ### 响应字段说明 | 字段 | 类型 | 描述 | |------|------|------| | id | string | 视频任务ID | | object | string | 对象类型，固定为 "video" | | model | string | 使用的模型名称 | | status | string | 任务状态（queued: 排队中, processing: 处理中, completed: 完成, failed: 失败） | | progress | integer | 处理进度（0-100） | | created_at | integer | 创建时间戳 | | size | string | 视频分辨率 | | seconds | string | 视频时长（秒） | | quality | string | 视频质量 | ## 查询视频 根据任务ID查询视频生成任务的状态和结果 ### API 端点 ``` GET /v1/videos/{video_id} ``` ### 路径参数 | 参数 | 类型 | 必填 | 描述 | |------|------|------|------| | video_id | string | 是 | 视频任务ID | ### 请求示例 ```bash curl 'https://ai.burncloud.com/v1/videos/video_123' \ -H "Authorization: Bearer sk-xxxx" ``` ### 响应格式 #### 200 - 成功响应 ```json { "id": "video_123", "object": "video", "model": "sora-2", "status": "completed", "progress": 100, "created_at": 1712697600, "size": "1024x1808", "seconds": "8", "quality": "standard", "url": "https://example.com/video.mp4" } ``` ### 响应字段说明 | 字段 | 类型 | 描述 | |------|------|------| | id | string | 视频任务ID | | object | string | 对象类型，固定为 "video" | | model | string | 使用的模型名称 | | status | string | 任务状态（queued: 排队中, processing: 处理中, completed: 完成, failed: 失败） | | progress | integer | 处理进度（0-100） | | created_at | integer | 创建时间戳 | | size | string | 视频分辨率 | | seconds | string | 视频时长（秒） | | quality | string | 视频质量 | | url | string | 视频下载链接（完成时） | ## 获取视频任务状态 根据任务ID获取视频生成任务的详细信息 ### API 端点 ``` GET /v1/videos/{video_id} ``` ### 路径参数 | 参数 | 类型 | 必填 | 描述 | |------|------|------|------| | video_id | string | 是 | 要获取的视频任务标识符 | ### 请求示例 ```bash curl 'https://ai.burncloud.com/v1/videos/video_123' \ -H "Authorization: Bearer sk-xxxx" ``` ### 响应格式 #### 200 - 成功响应 ```json { "id": "video_123", "object": "video", "model": "sora-2", "status": "completed", "progress": 100, "created_at": 1712697600, "completed_at": 1712698000, "expires_at": 1712784400, "size": "1024x1808", "seconds": "8", "quality": "standard", "remixed_from_video_id": null, "error": null } ``` ### 响应字段说明 | 字段 | 类型 | 描述 | |------|------|------| | id | string | 视频任务的唯一标识符 | | object | string | 对象类型，固定为 "video" | | model | string | 生成视频的模型名称 | | status | string | 视频任务的当前生命周期状态 | | progress | integer | 生成任务的近似完成百分比 | | created_at | integer | 任务创建时的Unix时间戳（秒） | | completed_at | integer | 任务完成时的Unix时间戳（秒），如果已完成 | | expires_at | integer | 可下载资源过期时的Unix时间戳（秒），如果已设置 | | size | string | 生成视频的分辨率 | | seconds | string | 生成视频片段的时长（秒） | | quality | string | 视频质量 | | remixed_from_video_id | string | 如果此视频是混音，则为源视频的标识符 | | error | object | 如果生成失败，则包含错误信息的对象 | ## 获取视频内容 下载已完成的视频内容 ### API 端点 ``` GET /v1/videos/{video_id}/content ``` ### 路径参数 | 参数 | 类型 | 必填 | 描述 | |------|------|------|------| | video_id | string | 是 | 要下载的视频标识符 | ### 查询参数 | 参数 | 类型 | 必填 | 描述 | |------|------|------|------| | variant | string | 否 | 要返回的可下载资源类型，默认为MP4视频 | ### 请求示例 ```bash curl 'https://ai.burncloud.com/v1/videos/video_123/content' \ -H "Authorization: Bearer sk-xxxx" \ -o "video.mp4" ``` ### 响应格式 #### 200 - 成功响应 直接返回视频文件流，Content-Type为 video/mp4 ### 响应头说明 | 字段 | 类型 | 描述 | |------|------|------| | Content-Type | string | 视频文件类型，通常为 video/mp4 | | Content-Length | string | 视频文件大小（字节） | | Content-Disposition | string | 文件下载信息 | ## 错误响应 ### 400 - 请求参数错误 ```json { "error": { "message": "Invalid request parameters", "type": "invalid_request_error", "code": "invalid_parameter" } } ``` ### 401 - 未授权 ```json { "error": { "message": "Invalid API key", "type": "authentication_error", "code": "invalid_api_key" } } ``` ### 403 - 无权限 ```json { "error": { "message": "Insufficient permissions", "type": "permission_error", "code": "insufficient_permissions" } } ``` ### 429 - 请求频率限制 ```json { "error": { "message": "Rate limit exceeded", "type": "rate_limit_error", "code": "rate_limit_exceeded" } } ``` ### 500 - 服务器内部错误 ```json { "error": { "message": "Internal server error", "type": "server_error", "code": "internal_error" } } ``` # Veo视频接口 ### Veo视频接口 ```bash curl --location 'https://csp.burncloud.com/v1/videos' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data '{ "model": "veo-3", "prompt": "一只猫在钓鱼,周围有蝴蝶在飞", "size": "1280x720", "seconds": "8" }' ```