Gemini 3 Pro (openai)
本页由 ModelFold 文档站根据上游官方 OpenAPI 文档同步生成。接口路径、参数、示例与官方保持一致；品牌与 API 域名已替换为 ModelFold。
接口
POST /gemini-3-pro/v1/chat/completions
完整 URL: https://ai.modelfold.online/gemini-3-pro/v1/chat/completions
鉴权：所有请求都需要
Authorization: Bearer <API_KEY>请求头。
WARNING
⚠️ 仅支持对话调用
该模型目前仅支持对话调用，暂未适配 Agent 场景。若将其接入 Agent 使用，可能会出现请求报错或结果异常。
流式响应支持
当请求中设置 stream: true 时，API 将以服务器发送事件（SSE）的形式返回响应，Content-Type 为 text/event-stream。这允许渐进式响应交付，消息增量会在生成时逐步发送。每个事件包含部分消息内容，使您能够在应用程序中实时显示响应。
流式响应格式：
Content-Type:
text/event-stream每个事件行以
data:开头，后跟 JSON事件包含增量消息增量
最终事件通过
finish_reason指示完成流的最后一块带 usage 与 credits_consumed，随后是 data: [DONE]。
- 多模态 — 支持文本、图像、视频、音频、PDF 输入
- 实时搜索 — 启用 Google 搜索增强
- 流式传输 — 支持服务器发送事件
- 灵活角色 — 支持多种消息角色
统一媒体文件格式
WARNING
在 messages 参数的 content 数组中，无论是图像、视频、音频还是其他文档类型，所有媒体文件都使用相同的格式结构：
type字段始终为"image_url"image_url字段名称保持不变- 唯一变化的是
url值，它指向相应的媒体文件地址
例如：图像、视频、音频、PDF 和其他文档都使用相同的 { type: 'image_url', image_url: { url: '...' } } 结构。
Tools 参数
tools 参数是一个可选数组，允许您定义模型可以调用的函数。数组可以包含多个对象。使用函数调用时，可以在数组中定义多个函数。
Google 搜索
使用此格式启用 Google 搜索增强：
json
{
"type": "function",
"function": {
"name": "googleSearch"
}
}这将通过 Google 搜索启用实时信息检索。
函数调用
定义带有参数的自定义函数。可以在 tools 数组中定义多个函数：
json
[
{
"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"]
}
}
},
{
"type": "function",
"function": {
"name": "get_stock_price",
"description": "获取指定股票代码的当前股价",
"parameters": {
"type": "object",
"properties": {
"symbol": {
"type": "string",
"description": "股票代码，例如：AAPL"
}
},
"required": ["symbol"]
}
}
}
]函数声明要求
在提示中实现函数调用时，您需要创建一个 tools 数组，其中包含一个或多个函数声明。您可以使用 JSON（具体来说是 OpenAPI 架构格式的选定子集）来定义函数。
单个函数声明可以包含以下参数：
name（字符串，必需）：函数的唯一名称（例如，get_weather_forecast、send_email）。使用不含空格或特殊字符的描述性名称（使用下划线或驼峰式命名法）。description（字符串，可选但推荐）：对函数用途和功能的清晰而详尽的说明。这对于模型了解何时使用函数至关重要。请具体说明，并在必要时提供示例（例如，"根据位置查找影院，还可以选择查找目前正在影院上映的电影。"）。parameters（对象，必需）：定义函数预期的输入参数。包含：type（字符串）：指定总体数据类型，必须为"object"。properties（对象）：列出各个参数，每个参数都具有以下属性：type（字符串）：参数的数据类型，例如string、integer、boolean、array。description（字符串）：对参数的用途和格式的说明。提供示例和限制条件（例如，"城市和州，例如'加利福尼亚州旧金山'或邮政编码（例如'95616'）。"）。enum（数组，可选）：如果参数值来自固定集，请使用enum列出允许的值，而不是仅在说明中描述它们。这有助于提高准确性（例如，"enum": ["daylight", "cool", "warm"]）。
required（数组）：一个字符串数组，列出了函数运行所必需的参数名称。
Response Format 参数
response_format 参数是一个可选的 JSON Schema 对象，定义响应的结构。提供此参数时，模型将生成符合此架构的响应。
JSON Schema 支持
response_format 遵循 JSON Schema 规范。支持的类型包括：
string：文本值number：浮点数integer：整数boolean：布尔值（true/false）object：包含键值对的结构化数据array：项目列表null：要允许 null 值，请在类型数组中添加"null"（例如，{"type": ["string", "null"]}）
特定类型的属性
对于 object 值：
properties：将属性名称映射到其架构定义的对象required：必需属性名称数组additionalProperties：控制是否允许不在properties中列出的属性
对于 string 值：
enum：用于分类的特定可能字符串列表format：指定字符串语法（例如，date-time、date、time）
对于 number 和 integer 值：
enum：特定可能数值列表minimum：包含在内的最小值maximum：包含在内的最大值
对于 array 值：
items：所有数组元素的架构定义prefixItems：前 N 个项的架构列表（类似元组的结构）minItems：数组中的最小项数maxItems：数组中的最大项数
示例
json
{
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "structured_output",
"strict": true,
"schema": {
"type": "object",
"properties": {
"response": {
"type": "string"
}
},
"required": [
"response"
]
}
}
}
}也支持 {"type":"json_object"}。
最佳实践
- 清晰的描述：在架构中使用
description字段清楚地解释每个属性的含义 - 强类型：尽可能使用特定类型（
integer、string、enum） - 提示工程：在提示中明确说明您希望模型提取或结构化的内容
- 验证：虽然结构化输出确保 JSON 在语法上正确，但请务必在应用程序代码中验证值的语义正确性
错误响应
错误以 HTTP 200 返回，响应体为 {"code": <int>, "msg": "<原因>"}。读取 choices/candidates 前请先判断 code（200 为成功）。
请求参数
请求体 (application/json)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
messages | array<object> | 是 | 消息对象数组。每个消息都有一个角色和内容。 统一媒体文件格式： 在 content 数组中，无论是图像、视频、音频还是其他文档类型，所有媒体文件都使用相同的格式结构： - type 字段始终为 "image_url"- image_url 字段名称保持不变- 唯一变化的是 url 值，它指向相应的媒体文件地址例如：图像、视频、音频、PDF 和其他文档都使用相同的 { type: 'image_url', image_url: { url: '...' } } 结构。 |
messages[].role | string | 是 | 消息角色 - developer: 开发者提供的指令，模型应遵循这些指令，无论用户消息如何。 - system: 开发者提供的指令，模型应遵循这些指令，无论用户消息如何。 - user: 最终用户发送的消息，包含提示或额外的上下文信息。 - assistant: 模型响应用户消息而发送的消息。 - tool: 工具消息的内容。 可选值： developer / system / user / assistant / tool。 示例：developer。 |
messages[].content | `array<object | object>` | 是 |
stream | boolean | 否 | 默认 false；设为 true 时以 SSE 流式返回。 默认值：false。 示例：false。 |
tools | array<object> | 否 | 可选，模型可以调用的工具数组。数组可以包含多个对象。支持两种格式： 1. Google 搜索： {"type": "function", "function": {"name": "googleSearch"}} - 通过 Google 搜索启用实时信息检索。2. 函数调用：定义自己的函数，包含 name、description 和 parameters。可以在数组中定义多个函数。函数使用 JSON（具体来说是 OpenAPI 架构格式的选定子集）来定义。 使用函数调用时，可以包含多个函数定义。 |
tools[].type | string | 是 | 工具类型。必须是 'function'。 可选值：function。 示例：function。 |
tools[].function | object | 是 | 用于网络访问增强的函数声明。 |
tools[].function.name | string | 是 | 函数名称。必须为 googleSearch。 |
tools[].function.description | string | 否 | 可选但推荐。清晰且具体地描述函数功能的说明。帮助模型理解何时调用此函数。 |
tools[].function.parameters | object | 否 | 定义函数参数的 JSON Schema 对象。自定义函数必需，'googleSearch' 不使用。遵循 JSON Schema 规范。 |
tools[].function.parameters.type | string | 是 | 必须是 'object' 用于函数参数 可选值：object。 示例：object。 |
tools[].function.parameters.properties | object | 是 | 将参数名称映射到其 JSON Schema 定义的对象 |
tools[].function.parameters.required | array<string> | 否 | 必需参数名称数组 |
include_thoughts | boolean | 否 | 默认 false。仅在 stream: true 时生效，思考摘要以 choices[].delta.reasoning_content 在正文前流式返回。 默认值：false。 示例：false。 |
reasoning_effort | string | 否 | 推理的力度。低力度响应更快，高力度响应更慢但解决更复杂的问题。默认为 "high"。 默认值："high"。 可选值：low / high。 示例：high。 |
response_format | object | 否 | 可选的 JSON Schema 对象，定义响应的结构。提供此参数时，模型将生成符合此架构的响应。 示例： <code>json<br>{<br> "type": "json_schema",<br> "json_schema": {<br> "name": "structured_output",<br> "strict": true,<br> "schema": {<br> "type": "object",<br> "properties": {<br> "response": {<br> "type": "string"<br> }<br> },<br> "required": [<br> "response"<br> ]<br> }<br> }<br>}<br></code>也支持 {"type":"json_object"}。 |
response_format.type | string | 是 | 仅 json_schema 值 |
response_format.json_schema | object | 是 | 用于定义响应结构的 JSON Schema 对象。提供此对象后，模型将生成符合此模式的响应。 |
response_format.json_schema.name | string | 是 | 仅structured_output 值 |
response_format.json_schema.strict | boolean | 是 | 是否启用严格模式 |
response_format.json_schema.schema | object | 是 | — |
response_format.json_schema.schema.type | string | 是 | 响应格式遵循 JSON Schema 规范。支持的类型包括： string：用于文本值 number：用于浮点数 integer：用于整数 boolean：用于 true/false 值 object：用于包含键值对的结构化数据 array：用于项目列表 null：要允许空值，请在类型数组后添加“null”。 |
response_format.json_schema.schema.properties | object | 是 | 对象将属性名称映射到其 JSON Schema 定义 |
response_format.json_schema.schema.required | array<string> | 是 | 必需属性名称数组 |
response_format.json_schema.schema.title | string | 是 | 模式简述 |
response_format.json_schema.schema.description | string | 是 | 模式的详细描述 |
请求示例
bash
curl -X POST "https://ai.modelfold.online/gemini-3-pro/v1/chat/completions" \
-H "Authorization: Bearer $MODELFOLD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "What is in this image?"
},
{
"type": "image_url",
"image_url": {
"url": "https://file.aiquickdraw.com/custom-page/akr/section-images/1759055072437dqlsclj2.png"
}
}
]
}
],
"tools": [
{
"type": "function",
"function": {
"name": "googleSearch"
}
}
],
"stream": true,
"include_thoughts": true,
"reasoning_effort": "high",
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "structured_output",
"strict": true,
"schema": {
"type": "object",
"properties": {
"response": {
"type": "string"
}
},
"required": [
"response"
]
}
}
}
}'json
{
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "What is in this image?"
},
{
"type": "image_url",
"image_url": {
"url": "https://file.aiquickdraw.com/custom-page/akr/section-images/1759055072437dqlsclj2.png"
}
}
]
}
],
"tools": [
{
"type": "function",
"function": {
"name": "googleSearch"
}
}
],
"stream": true,
"include_thoughts": true,
"reasoning_effort": "high",
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "structured_output",
"strict": true,
"schema": {
"type": "object",
"properties": {
"response": {
"type": "string"
}
},
"required": [
"response"
]
}
}
}
}响应
200 — 请求成功。当提供 response_format 时，响应将符合指定的 JSON 架构。否则，返回标准的聊天完成格式。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 否 | 聊天完成的唯一标识符 示例：chatcmpl-example-123。 |
object | string | 否 | 对象类型 示例：chat.completion。 |
created | integer | 否 | 完成创建时的 Unix 时间戳 示例：1677652288。 |
choices | array<object> | 否 | 完成选项数组 |
choices[].index | integer | 是 | 选项索引 示例：0。 |
choices[].message | object | 是 | — |
choices[].message.role | string | 是 | 示例：assistant。 |
choices[].message.content | string | 是 | 消息内容 |
choices[].finish_reason | string | 是 | 完成完成的原因 示例：stop。 |
usage | object | 否 | — |
usage.prompt_tokens | integer | 是 | 提示中的 token 数量 示例：10。 |
usage.completion_tokens | integer | 是 | 完成中的 token 数量 示例：50。 |
usage.total_tokens | integer | 是 | 总 token 数量 示例：60。 |
json
{
"id": "chatcmpl-example-123",
"object": "chat.completion",
"created": 1677652288,
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "A serene mountain landscape at sunrise"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 10,
"completion_tokens": 50,
"total_tokens": 60
}
}