Gemini 原生接口

Gemini 原生协议使用 contents 和 parts 表达输入。它与 OpenAI 的 messages 结构不同，适合已经使用 Google Gen AI SDK 或需要保留 Gemini 内容结构的项目。

以控制台为准

请先确认控制台中目标模型是否开放 Gemini 原生协议。将示例中的 your-gemini-model 替换为控制台显示的完整模型 ID；可用模型和参数不在文档中写死。

generateContent

上游 Gemini REST 协议的文本生成路径为 v1beta/models/{model}:generateContent。在 FlashCoding.AI 上可按下面的格式测试：

curl "https://flashcoding.ai/v1beta/models/your-gemini-model:generateContent" \
  -H "x-goog-api-key: sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {"text": "请只回复：连接成功"}
        ]
      }
    ]
  }'

成功时，文本通常位于 candidates[].content.parts[] 中。一个响应可能包含多个候选或多个内容块，解析时应检查类型与字段是否存在。

鉴权与路径必须匹配协议

本节使用 Gemini 原生的 x-goog-api-key 请求头。如果控制台为你的渠道给出了不同的专用前缀或鉴权方式，应以控制台为准；不要把原生请求体发送到 /v1/chat/completions。

系统指令与生成参数

系统指令使用顶层 systemInstruction，生成参数放在 generationConfig 中：

curl "https://flashcoding.ai/v1beta/models/your-gemini-model:generateContent" \
  -H "x-goog-api-key: sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "systemInstruction": {
      "parts": [
        {"text": "你是一个回答简洁的中文助手。"}
      ]
    },
    "contents": [
      {
        "role": "user",
        "parts": [
          {"text": "给出两个保护 API Key 的建议。"}
        ]
      }
    ],
    "generationConfig": {
      "maxOutputTokens": 512
    }
  }'

不同模型支持的生成参数可能不同。先发送只有 contents 的最小请求，再逐项增加参数，能更快定位兼容性问题。

多轮对话

原生协议通过交替发送 user 和 model 内容保存上下文：

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "我的项目代号是 Sakura。"}]
    },
    {
      "role": "model",
      "parts": [{"text": "好的，我记住了。"}]
    },
    {
      "role": "user",
      "parts": [{"text": "项目代号是什么？"}]
    }
  ]
}

API 调用通常不替你长期保存会话。应用应保存必要历史，同时控制上下文长度和敏感信息的保留范围。

OpenAI 兼容方式

Google 的 Gemini API 提供 OpenAI 兼容形态；当客户端只能配置 OpenAI 接口时，也可以使用 FlashCoding.AI 的统一入口。模型仍须从控制台选择。

curl https://flashcoding.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-gemini-model",
    "messages": [
      {"role": "user", "content": "请只回复：连接成功"}
    ]
  }'

两种协议不要混用：

使用场景	请求路径	请求结构
Gemini 原生	/v1beta/models/{model}:generateContent	contents / parts
OpenAI 兼容	/v1/chat/completions	messages

原生协议特有能力不一定能通过兼容层完整表达。反过来，某些 OpenAI 参数也不能原样放进 generationConfig。

排查要点

• 400：检查 contents、parts 和角色名称，不要使用 OpenAI 的 assistant 角色。
• 401 / 403：检查 Key、鉴权请求头，以及目标模型是否对当前账户开放。
• 404：检查模型 ID、API 版本和路径中的 :generateContent。
• 返回为空：检查 candidates、结束原因和安全相关反馈，再决定是否调整输入。

继续查看状态码与错误或Gemini CLI 配置。