Gemini 3.8 Flash (openai)

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

接口

POST /gemini-3-8-flash-openai/v1/chat/completions

完整 URL: https://ai.modelfold.online/gemini-3-8-flash-openai/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 参数是一个可选数组，允许您定义模型可以调用的函数。数组可以包含多个对象。使用函数调用时，可以在数组中定义多个函数。

函数调用

定义带有参数的自定义函数。可以在 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（数组）：一个字符串数组，列出了函数运行所必需的参数名称。

错误响应

错误以 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>`	否	可选，模型可以调用的工具数组。数组可以包含多个对象。 Google 搜索：`{"type": "function", "function": {"name": "googleSearch"}}` - 通过 Google 搜索启用实时信息检索。
`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`	否	是否包含思考输出。示例：`true`。
`reasoning_effort`	`string`	否	thinking level 等级。可选值：`low` / `high`。示例：`high`。

请求示例

bash

curl -X POST "https://ai.modelfold.online/gemini-3-8-flash-openai/v1/chat/completions" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "图片里面有什么?"
        },
        {
          "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": "图片里面有什么?"
        },
        {
          "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 — 请求成功。

参数	类型	必填	说明
`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`。
`credits_consumed`	`number`	否	本次请求扣除的积分示例：`0.01`。

json

{
  "id": "chatcmpl-c90c370251f24fd4b2d85a052e38f47a",
  "object": "chat.completion",
  "created": 1791213382,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "OK"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 6,
    "completion_tokens": 1,
    "total_tokens": 97,
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  },
  "credits_consumed": 0.01
}

500 — Server error.

参数	类型	必填	说明
`code`	`integer`	是	Response status code - 200: Success - Request has been processed successfully - 401: Unauthorized - Authentication credentials are missing or invalid - 402: Insufficient Credits - Account does not have enough credits to perform the operation - 404: Not Found - The requested resource or endpoint does not exist - 408: Timeout - No result has been returned for over 10 minutes. - 422: Validation Error - The request parameters failed validation checks - 429: Rate Limited - Request limit has been exceeded for this resource - 455: Service Unavailable - System is currently undergoing maintenance - 500: Server Error - An unexpected error occurred while processing the request - 501: Generation Failed - Content generation task failed - 505: Feature Disabled - The requested feature is currently disabled
`msg`	`string`	是	Response message, error description when failed
`data`	`object`	是	—

json

{
  "code": 500,
  "msg": "Server Error - An unexpected error occurred while processing the request",
  "data": null
}

Gemini 3.8 Flash (openai) ​

接口 ​

流式响应支持 ​

统一媒体文件格式 ​

Tools 参数 ​

函数声明要求 ​

错误响应 ​

请求参数 ​

请求体 (application/json) ​

请求示例 ​

响应 ​

200 — 请求成功。 ​

500 — Server error. ​

Gemini 3.8 Flash (openai)

接口

流式响应支持

统一媒体文件格式

Tools 参数

函数声明要求

错误响应

请求参数

请求体 (application/json)

请求示例

响应

200 — 请求成功。

500 — Server error.