Gemini API

路径

Gemini API family 当前公开两个生成 operation：GenerateContent 用于一次性返回完整结果，StreamGenerateContent 用于以 Gemini 原生流式事件逐步返回结果。两者共享 Gemini 鉴权、模型商品和上游 capability 选择，但路径和响应交付方式不同。

生成请求路径必须包含 /v1beta/models/{model}: 前缀；模型列表则使用上表的 /v1beta/models 或 /v1beta/models/。{model} 这一段可以写 gemini-2.5-flash 或 models/gemini-2.5-flash，网关只会归一化模型值内部的 models/ 前缀；模型列表响应会按 Gemini 习惯返回 models/{publicModel}。

鉴权

完整 Header 规则见 Base URL 与鉴权 和 请求头。本页示例统一使用 x-goog-api-key。Bearer 只作为兼容方式；x-api-key 和 URL ?key= 会被拒绝。

非流式请求

curl https://dingjiai.com/v1beta/models/gemini-2.5-flash:generateContent \
  -H "x-goog-api-key: YOUR_USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "用一句话介绍顶级AI网关" }
        ]
      }
    ]
  }'

请求体里的 model 和 stream 字段不会作为顶级AI模型选择依据。模型以路径里的 {model} 为准。

流式请求

curl -N https://dingjiai.com/v1beta/models/gemini-2.5-flash:streamGenerateContent \
  -H "x-goog-api-key: YOUR_USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "列出三个接入注意事项" }
        ]
      }
    ]
  }'

Gemini 流式必须使用 streamGenerateContent 路径。generateContent 请求体里写 "stream": true 会返回 stream_not_supported。

usageMetadata 与结算

非流式和流式响应都优先使用上游 usageMetadata；流式会保留最后一个有效值。按 token 计费的合法 JSON 对象，或已经交付至少一个上游/model chunk 的 stream，在 usageMetadata 缺失或无效时，可能按文本、thoughts 和 functionCall 等已生成输出使用保守下界估算；合法已交付 envelope/上游 chunk 没有可提取输出时最少按 1 个 output token。已交付内容后上游断流或客户端取消，仍按 partial usage 或已交付输出下限结算。真正空白/畸形 non-stream body 会对客失败并零扣费；上游/model 零 chunk 流已经提交 2xx，body 可能为空或只含网关 SSE keepalive，不能改写成错误体，网关会记录失败、释放预留并零扣费。Gemini 图片商品不依赖 token usageMetadata，只按实际返回的有效图片数计费；没有有效图片时失败关闭且零扣费。

模型列表

curl https://dingjiai.com/v1beta/models \
  -H "x-goog-api-key: YOUR_USER_API_KEY"

模型列表只返回当前 Gemini 调用入口公开可见、已启用，并且存在可用上游候选的模型商品。普通 token 商品的 supportedGenerationMethods 包含 generateContent 和 streamGenerateContent；per_image 图片商品只支持 generateContent，不会宣称支持 streamGenerateContent。因此，流式能力应以每个模型商品返回的 supportedGenerationMethods 为准。