AI 接口对接文档中心

1. 概述

本接口透传 Gemini GenerateContent 原生请求和响应，用于调用已开通的 Gemini 模型。非流式调用 invokeFuncName 使用 generateContent，流式调用 invokeFuncName 使用 streamGenerateContent。

baseUrl: https://token.soar.qjclouds.cn/laserStreamEr/00000000
completionsPath: /v1beta/models/{model}:{invokeFuncName}
标准地址:POST {baseUrl}{completionsPath}
鉴权：Authorization: Bearer <api_key>
请求体:标准 Gemini GenerateContent JSON

地址拼接：{baseUrl}{completionsPath}
流式 https://token.soar.qjclouds.cn/laserStreamEr/00000000/v1beta/models/{model}:streamGenerateContent
非流式 https://token.soar.qjclouds.cn/laserStreamEr/00000000/v1beta/models/{model}:generateContent

2. 接入前置条件

项	说明
`api_key`	访问密钥（控制台生成），用于 Bearer 鉴权。
`model`	已在平台开通且配置了 Gemini 协议的模型编码，同时作为请求路径参数。

3. 鉴权

Header	必填	说明
`Authorization`	是	`Bearer <api_key>`
`Content-Type`	是	`application/json`
`Accept`	流式建议	流式设为 `text/event-stream`；非流式可设为 `application/json`。

缺失 Authorization 或 api_key 无效时，直接返回 401。

4. 对话补全

4.1 请求体

请求体采用 Gemini GenerateContentRequest 原生 JSON 结构；contents 为必填字段。

字段	类型	必填	说明
`contents`	array<Content>	是	当前对话内容；每项由可选 `role` 与必填 `parts[]` 组成。单轮传一个 Content，多轮按历史顺序传入。
`systemInstruction`	Content	否	开发者设置的系统指令；目前以文本内容为主。
`tools`	array<Tool>	否	模型可调用的工具集合，例如函数声明或代码执行工具。
`toolConfig`	ToolConfig	否	为 `tools` 指定函数调用策略等配置。
`safetySettings`	array<SafetySetting>	否	安全过滤设置；同一安全类别最多配置一次，会覆盖该类别默认设置。
`generationConfig`	GenerationConfig	否	生成与输出配置，如 `temperature`、`topP`、`topK`、`maxOutputTokens`、`stopSequences`、`responseMimeType`、`responseSchema` 与 `thinkingConfig`。
`cachedContent`	string	否	要作为上下文使用的缓存内容资源名，格式为 `cachedContents/{cachedContent}`。
`serviceTier`	enum	否	请求服务层级；可用枚举以模型与上游支持范围为准。
`store`	boolean	否	配置本次请求的日志记录行为；设置后优先于项目级配置。

4.1.1 Content 与 Part

contents[].parts[] 承载实际输入。常用 Part 包括 text、inlineData（内嵌多媒体数据）、fileData（文件 URI）、functionCall 与 functionResponse；是否支持取决于模型能力。

4.2 请求示例

JSON

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "介绍一下你自己"
        }
      ]
    }
  ]
}

4.3 响应

非流式响应为 Gemini 原生 GenerateContentResponse。常用字段包括 candidates[]、candidates[].content.parts[]、finishReason、promptFeedback 与 usageMetadata；文本结果位于候选项的 content.parts[].text。

以下为本次请求的响应示例。thoughtSignature 是模型返回的不透明长字符串，此处仅保留字段并省略具体内容。

JSON

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "你好！我是 **Gemini**，是由 **Google** 训练的大型语言模型。\n\n作为一个人工智能助手，我的目标是为你提供高效、准确且富有创意的帮助。我可以处理各种各样的任务，主要包括：\n\n1. **内容创作与文本处理**：撰写文章、故事、邮件、报告，或者对长文本进行摘要、润色、改写和校对。\n2. **编程与技术支持**：编写、解释和调试多种编程语言的代码（如 Python、JavaScript、C++、Java 等），解答算法和技术架构问题。\n3. **解答疑问与知识检索**：涵盖科学、历史、哲学、文化、商业和日常生活等多个领域的问答。\n4. **语言与翻译**：支持全球多种语言之间的流畅翻译，并能协助进行语言学习和语法解析。\n5. **逻辑推理与分析**：协助解决复杂的逻辑谜题、数学问题或进行结构化的数据与信息分析。\n\n作为 **Gemini 3.7 Flash**，我的特点是**响应迅速、思维敏捷**，同时具备强大的多任务处理和深度推理能力。\n\n无论你是需要解决具体的工作/学习难题、激发灵感，还是想探讨某个话题，都可以随时告诉我。今天有什么我可以帮你的吗？",
            "thoughtSignature": "<省略>"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ],
  "modelVersion": "gemini-3.7-flash",
  "responseId": "2yKeatyjLqT2jNAPiv7BsQ4",
  "usageMetadata": {
    "candidatesTokenCount": 274,
    "promptTokenCount": 3,
    "thoughtsTokenCount": 703,
    "totalTokenCount": 980
  }
}

4.4 错误响应

错误响应遵循 Google API 错误对象结构。常见状态：400 参数无效、401 鉴权失败、404 模型或路径不存在、429 限流或配额不足、500 服务异常。

5. 流式对话补全

5.1 请求体

请求体字段与 4.1 相同；调用 :streamGenerateContent 路径即可获取 SSE 响应，无需额外的 stream 字段。

5.2 请求示例

JSON

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "介绍一下你自己"
        }
      ]
    }
  ]
}

5.3 响应

响应为一系列 GenerateContentResponse SSE 数据帧。每帧可能包含增量候选内容，最终帧通常包含 finishReason 和 usageMetadata。

以下为本次请求的响应示例。为便于阅读，中间连续的文本增量帧和最终帧中的不透明 thoughtSignature 已省略；客户端应按顺序拼接各帧的 candidates[].content.parts[].text。

SSE

data: {"candidates":[{"content":{"parts":[{"text":"你好！我是 **Gemini**，是由 Google 训练"}],"role":"model"}}],"modelVersion":"gemini-3.7-flash","responseId":"6SOeauDvCPLTi9sPs7ej0QE","usageMetadata":{}}

data: {"candidates":[{"content":{"parts":[{"text":"的大型语言模型（具体版本是 **Gemini 3.7 Flash**）。\n\n作为一款先进的 AI "}],"role":"model"}}],"modelVersion":"gemini-3.7-flash","responseId":"6SOeauDvCPLTi9sPs7ej0QE","usageMetadata":{}}

data: {"candidates":[{"content":{"parts":[{"text":"助手，我的特点是**响应迅速、逻辑思维能力强**，并且能够理解和处理多种复杂任务。\n\n我"}],"role":"model"}}],"modelVersion":"gemini-3.7-flash","responseId":"6SOeauDvCPLTi9sPs7ej0QE","usageMetadata":{}}

... 中间的文本增量帧省略 ...

data: {"candidates":[{"content":{"parts":[{"text":"您。\n\n请问今天有什么我可以帮您的吗？"}],"role":"model"}}],"modelVersion":"gemini-3.7-flash","responseId":"6SOeauDvCPLTi9sPs7ej0QE","usageMetadata":{}}

data: {"candidates":[{"content":{"parts":[{"text":"","thoughtSignature":"<省略>"}],"role":"model"},"finishReason":"STOP"}],"modelVersion":"gemini-3.7-flash","responseId":"6SOeauDvCPLTi9sPs7ej0QE","usageMetadata":{"candidatesTokenCount":306,"promptTokenCount":3,"thoughtsTokenCount":808,"totalTokenCount":1117}}

5.4 错误响应

建立流前的错误以 HTTP 状态码和 Google API 错误对象返回；流建立后的异常以 SSE 数据帧异常或流中断体现。