Gemini API 接入指南：Google 兼容调用与超大上下文

一、概述

本站提供 Google Gemini API 格式兼容接入，支持 generateContent 与流式生成两种调用方式。使用 Google GenAI SDK 或 Gemini 兼容客户端的项目，把请求地址指向本站网关的 Gemini 入口、密钥换成站内 sk- 密钥即可接入。

当前可用的 Gemini 系列模型以模型广场为准（如 gemini-3.7-flash、gemini-3.6-flash、gemini-3.5-flash、gemini-3.5-flash-lite 等），完整清单与单价通过 GET /v1/models 查询。

二、接口地址

方法	路径	说明
POST	/v1beta/models/{model}:generateContent	Gemini 生成入口，请求体为 generateContent 载荷
POST	/v1beta/models/{model}:streamGenerateContent?alt=sse	流式生成（SSE）
GET	/v1/models	模型与单价列表（无需鉴权）

网关地址：https://www.azztimes.com。模型名拼在 URL（/v1beta/models/{model}:generateContent，与 Google 官方一致）；请求体为 generateContent 载荷。

三、鉴权方式

与本站其他接口一致，使用站内 sk- 密钥：

Authorization: Bearer sk-你的密钥

也兼容 x-api-key 与 Google 官方 x-goog-api-key: sk-你的密钥 头。

四、快速开始（curl）

4.1 非流式

curl -X POST https://www.azztimes.com/v1beta/models/gemini-3.7-flash:generateContent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的密钥" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "用一句话介绍 Gemini API"}]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 512
    }
  }'

4.2 携带系统指令（systemInstruction）

curl -X POST https://www.azztimes.com/v1beta/models/gemini-3.7-flash:generateContent \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-你的密钥" \
  -d '{
    "model": "gemini-3.5-flash",
    "systemInstruction": {
      "parts": [{"text": "你是一位资深的 API 集成工程师，回答请简洁。"}]
    },
    "contents": [
      {"role": "user", "parts": [{"text": "如何选择流式与非流式接口？"}]}
    ]
  }'

五、请求参数

字段	类型	必填	说明
model	string	是	模型 slug，如 gemini-3.7-flash
contents	array	是	对话内容，元素为 {role, parts[]}；role 取值 user / model
contents[].parts	array	是	内容块，常用 {text} 文本块
systemInstruction	object	否	系统指令，结构 {parts: [{text}]}
generationConfig.temperature	number	否	采样温度，默认 1.0
generationConfig.topP	number	否	核采样
generationConfig.topK	int	否	Top-K 采样
generationConfig.maxOutputTokens	int	否	最大输出 token 数
generationConfig.stopSequences	array	否	停止序列
stream	bool	否	是否流式返回，默认 false

六、响应结构

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{"text": "Gemini API 支持文本、多模态输入与流式输出。"}]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 16,
    "candidatesTokenCount": 20,
    "totalTokenCount": 36
  }
}

字段	说明
candidates[].content.parts[].text	模型生成的文本
candidates[].finishReason	结束原因：STOP / MAX_TOKENS / SAFETY / RECITATION
usageMetadata.promptTokenCount	输入 token 数（计费依据）
usageMetadata.candidatesTokenCount	输出 token 数（计费依据）
usageMetadata.totalTokenCount	总 token 数

七、流式输出

请求体加 "stream": true 后，服务端以 SSE 逐块返回候选内容：

data: {"candidates": [{"content": {"parts": [{"text": "Gemini"}]}, "index": 0}]}

data: {"candidates": [{"content": {"parts": [{"text": " API 支持流式"}]}, "index": 0}]}

data: {"candidates": [{"content": {"parts": [{"text": "输出。"}]}, "index": 0, "finishReason": "STOP"}]}

客户端解析每个 data: 行并拼接 candidates[0].content.parts[0].text；最后一个 chunk 的 finishReason 为 STOP 时表示生成完成。

八、常见错误码

HTTP 状态码	含义	处理建议
400	请求格式错误（contents 缺失、模型不存在等）	检查请求体与模型名
401	无效或缺失 API 密钥	检查 Authorization / x-api-key 头
403	密钥停用、余额不足，或该密钥未授权此模型/路线	充值或检查密钥授权
404	模型或端点不存在	确认模型 slug
429	请求过于频繁	退避重试
500	服务内部错误	稍后重试，持续异常请联系客服

错误响应体统一为 {"code": 状态码, "message": "错误说明", "data": null} 结构。

九、兼容性说明

• Google GenAI SDK（google-genai）可通过自定义 endpoint 接入。
• 支持各类以 generateContent 为目标的 Gemini 兼容客户端。
• 模型名以 GET /v1/models 返回的 slug 为准。