# tokenssr接口文档 # 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://king.tokenssr.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $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://king.tokenssr.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $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://king.tokenssr.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $API_KEY" \ -d '{ "model": "gpt-4.1", "messages": [ { "role": "developer", "content": "你是一个有帮助的助手。" }, { "role": "user", "content": "你好！" } ], "stream": true }' ``` **流式响应示例:** ```Plain Text {"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://king.tokenssr.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $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://king.tokenssr.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $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 } ``` ## 📮 请求 ### 端点 ```Plain Text POST /v1/chat/completions ``` 创建给定聊天对话的模型响应。更多详情请参阅文本生成、视觉和音频指南。 ### 鉴权方法 在请求头中包含以下内容进行 API 密钥认证： ```Plain Text Authorization: Bearer $API_KEY ``` 其中 `$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） \!\!\! info "官方文档" [OpenAI Responses](https://platform.openai.com/docs/api-reference/responses) ## 📝 简介 OpenAI 最先进的模型响应接口。支持文本和图像输入，以及文本输出。创建与模型的有状态交互，将先前响应的输出用作输入。通过文件搜索、网络搜索、计算机使用等内置工具扩展模型的能力。使用函数调用允许模型访问外部系统和数据。 相关指南可参阅OpenAI官网：[Responses](https://platform.openai.com/docs/guides/migrate-to-responses) ## 💡 请求示例 ### 基础文本响应 ✅ ```Bash curl https://king.tokenssr.com/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $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://king.tokenssr.com/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $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://king.tokenssr.com/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $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://king.tokenssr.com/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $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://king.tokenssr.com/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $API_KEY" \ -d '{ "model": "gpt-4.1", "instructions": "你是一个有帮助的助手。", "input": "你好！", "stream": true }' ``` **流式响应示例:** ```Plain Text 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://king.tokenssr.com/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $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://king.tokenssr.com/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $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": {} } ``` ## 📮 请求 ### 端点 ```Plain Text POST /v1/responses ``` 创建模型响应。提供文本或图像输入以生成文本或JSON输出。让模型调用您自己的自定义代码或使用内置工具（如网络搜索或文件搜索）将您自己的数据用作模型响应的输入。 ### 鉴权方法 在请求头中包含以下内容进行 API 密钥认证： ```Plain Text Authorization: Bearer $API_KEY ``` 其中 `$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） \!\!\! info "官方文档" \- [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://king.tokenssr.com/v1/messages \ --header "anthropic-version: 2023-06-01" \ --header "content-type: application/json" \ --header "x-api-key: $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://king.tokenssr.com/v1/messages \ --header "anthropic-version: 2023-06-01" \ --header "content-type: application/json" \ --header "x-api-key: $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://king.tokenssr.com/v1/messages \ --header "anthropic-version: 2023-06-01" \ --header "content-type: application/json" \ --header "x-api-key: $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://king.tokenssr.com/v1/messages \ --header "anthropic-version: 2023-06-01" \ --header "content-type: application/json" \ --header "x-api-key: $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" } ``` ## 📮 请求 ### 端点 ```Plain Text POST /v1/messages ``` ### 鉴权方法 在请求头中包含以下内容进行 API 密钥认证： ```Plain Text x-api-key: $API_KEY ``` 其中 `$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`: 服务器内部错误 # Google Gemini 对话格式（Generate Content） \!\!\! info "官方文档" [Google Gemini Generating content API](https://ai.google.dev/api/generate-content) ## 📝 简介 Google Gemini API 支持使用图片、音频、代码、工具等生成内容。给定输入 GenerateContentRequest 生成模型响应。支持文本生成、视觉理解、音频处理、长上下文、代码执行、JSON 模式、函数调用等多种功能。 ## 💡 请求示例 ### 基础文本对话 ✅ ```Bash curl "https://king.tokenssr.com/v1beta/models/gemini-2.0-flash:generateContent?key=$API_KEY" \ -H 'Content-Type: application/json' \ -X POST \ -d '{ "contents": [{ "parts":[{"text": "Write a story about a magic backpack."}] }] }' 2> /dev/null ``` ### Nano Banana生图✅ ```JSON curl -X POST "https://king.tokenssr.com/v1beta/models/gemini-3-pro-image-preview:generateContent/" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "contents": [ { "role": "user", "parts": [ { "text": "draw a cat" } ] } ], "generationConfig": { "responseModalities": [ "TEXT", "IMAGE" ], "imageConfig": { "aspectRatio": "16:9", "imageSize": "2K" } } }' ``` ### 图像分析对话 ✅ ```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://king.tokenssr.com/v1beta/models/gemini-2.0-flash:generateContent?key=$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://king.tokenssr.com/v1beta/models/gemini-2.0-flash:generateContent?key=$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://king.tokenssr.com/v1beta/models/gemini-2.0-flash:generateContent?key=$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://king.tokenssr.com/v1beta/models/gemini-2.0-flash:generateContent?key=$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://king.tokenssr.com/v1beta/models/gemini-2.0-flash:generateContent?key=$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://king.tokenssr.com/v1beta/models/gemini-2.0-flash:generateContent?key=$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://king.tokenssr.com/v1beta/models/gemini-2.0-flash:generateContent?key=$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://king.tokenssr.com/v1beta/models/gemini-2.0-flash:streamGenerateContent?alt=sse&key=$API_KEY" \ -H 'Content-Type: application/json' \ --no-buffer \ -d '{ "contents": [{ "parts": [{"text": "写一个关于魔法背包的故事"}] }] }' ``` ### 代码执行 ✅ ```Bash curl "https://king.tokenssr.com/v1beta/models/gemini-2.0-flash:generateContent?key=$API_KEY" \ -H 'Content-Type: application/json' \ -X POST \ -d '{ "contents": [{ "parts": [{"text": "计算斐波那契数列的第10项"}] }], "tools": [{ "codeExecution": {} }] }' ``` ### 生成配置 ✅ ```Bash curl https://king.tokenssr.com/v1beta/models/gemini-2.0-flash:generateContent?key=$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://king.tokenssr.com/v1beta/models/gemini-2.0-flash:generateContent?key=$API_KEY" \ -H 'Content-Type: application/json' \ -X POST \ -d @request.json 2> /dev/null ``` ### 系统指令 ✅ ```Bash curl "https://king.tokenssr.com/v1beta/models/gemini-2.0-flash:generateContent?key=$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"}}}' ``` ## 📮 请求 ### 端点 #### 生成内容 ```Plain Text POST https://king.tokenssr.com/v1beta/{model=models/*}:generateContent ``` #### 流式生成内容 ```Plain Text POST https://king.tokenssr.com/v1beta/{model=models/*}:streamGenerateContent ``` ### 鉴权方法 在请求URL参数中包含API密钥： ```Plain Text ?key=$API_KEY ``` 其中 `$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" } ] } ] } } ```