ModelFold Docs

简体中文

English

简体中文

English

Appearance

Gemini 3.1 Pro (openai) ​

本页由 ModelFold 文档站根据上游官方 OpenAPI 文档同步生成。接口路径、参数、示例与官方保持一致；品牌与 API 域名已替换为 ModelFold。

接口 ​

POST /gemini-3.1-pro/v1/chat/completions

完整 URL: https://ai.modelfold.online/gemini-3.1-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 搜索启用实时信息检索。

错误响应 ​

错误以 HTTP 200 返回，响应体为 {"code": <int>, "msg": "<原因>"}。读取 choices/candidates 前请先判断 code（200 为成功）。

请求参数 ​

请求体 (application/json) ​

参数类型必填说明
messagesarray&lt;object&gt;是消息对象数组。每个消息都有一个角色和内容。
统一媒体文件格式：
在 content 数组中，无论是图像、视频、音频还是其他文档类型，所有媒体文件都使用相同的格式结构：
- type 字段始终为 "image_url"
- image_url 字段名称保持不变
- 唯一变化的是 url 值，它指向相应的媒体文件地址
例如：图像、视频、音频、PDF 和其他文档都使用相同的 { type: 'image_url', image_url: { url: '...' } } 结构。
  messages[].rolestring是消息角色
- developer: 开发者提供的指令，模型应遵循这些指令，无论用户消息如何。
- system: 开发者提供的指令，模型应遵循这些指令，无论用户消息如何。
- user: 最终用户发送的消息，包含提示或额外的上下文信息。
- assistant: 模型响应用户消息而发送的消息。
- tool: 工具消息的内容。 可选值：developer / system / user / assistant / tool。 示例：developer。
  messages[].content`array<objectobject>`是
streamboolean否默认 false；设为 true 时以 SSE 流式返回。 默认值：false。 示例：false。
toolsarray&lt;object&gt;否可选，模型可以调用的工具数组。数组可以包含多个对象。
Google 搜索：{"type": "function", "function": {"name": "googleSearch"}} - 通过 Google 搜索启用实时信息检索。
  tools[].typestring是工具类型。必须是 'function'。 可选值：function。 示例：function。
  tools[].functionobject是用于网络访问增强的函数声明。
    tools[].function.namestring是函数名称。必须为 googleSearch。
    tools[].function.descriptionstring否可选但推荐。清晰且具体地描述函数功能的说明。帮助模型理解何时调用此函数。
    tools[].function.parametersobject否定义函数参数的 JSON Schema 对象。自定义函数必需，'googleSearch' 不使用。遵循 JSON Schema 规范。
      tools[].function.parameters.typestring是必须是 'object' 用于函数参数 可选值：object。 示例：object。
      tools[].function.parameters.propertiesobject是将参数名称映射到其 JSON Schema 定义的对象
      tools[].function.parameters.requiredarray&lt;string&gt;否必需参数名称数组
include_thoughtsboolean否默认 false。仅在 stream: true 时生效，思考摘要以 choices[].delta.reasoning_content 在正文前流式返回。 默认值：false。 示例：false。
reasoning_effortstring否推理的力度。低力度响应更快，高力度响应更慢但解决更复杂的问题。默认为 "high"。 默认值："high"。 可选值：low / high。 示例：high。

请求示例 ​

bash
curl -X POST "https://ai.modelfold.online/gemini-3.1-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"
}'
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"
}

响应 ​

200 — 请求成功。 ​

参数类型必填说明
idstring否聊天完成的唯一标识符 示例：chatcmpl-example-123。
objectstring否对象类型 示例：chat.completion。
createdinteger否完成创建时的 Unix 时间戳 示例：1677652288。
choicesarray&lt;object&gt;否完成选项数组
  choices[].indexinteger是选项索引 示例：0。
  choices[].messageobject是—
    choices[].message.rolestring是示例：assistant。
    choices[].message.contentstring是消息内容
  choices[].finish_reasonstring是完成完成的原因 示例：stop。
usageobject否—
  usage.prompt_tokensinteger是提示中的 token 数量 示例：10。
  usage.completion_tokensinteger是完成中的 token 数量 示例：50。
  usage.total_tokensinteger是总 token 数量 示例：60。
json
{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "Hello! How can I help you today?",
        "role": "assistant"
      }
    }
  ],
  "created": 1768283309,
  "credits_consumed": 0.27,
  "id": "chatcmpl-********************z6IaTP6H",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 383,
    "completion_tokens_details": {
      "audio_tokens": 0,
      "text_tokens": 0,
      "reasoning_tokens": 374
    },
    "prompt_tokens": 1,
    "total_tokens": 384
  }
}

500 — 服务器错误 ​

ModelFold — 一个 API，接入所有主流 AI 模型。

© 2026 ModelFold