Gemini API 国内接入教程：OpenAI Compatible 调用与验证

结论先说： 如果项目已经使用 OpenAI SDK，可以先通过 AI快站的 OpenAI Compatible 入口调用当前开放的 Gemini 模型。正确顺序是查询 /v1/models、复制真实模型 ID、完成最小文本请求，再单独验证图像输入、流式输出和结构化能力。

开始前准备

Google 官方提供 OpenAI Compatibility 接入方式，但不同网关和模型支持的字段仍可能不同。不要因为文本对话成功，就默认原生 Gemini API 的文件、缓存、实时或多模态能力全部可用。

第一步：获取真实模型 ID

export AIFAST_API_KEY="你的_API_Key"

curl --fail-with-body --silent --show-error \
  https://www.aifast.club/v1/models \
  -H "Authorization: Bearer $AIFAST_API_KEY"

从返回的 data 数组中复制当前账号可用的 Gemini 模型 ID。模型名称、版本、开放状态和价格都可能更新，因此不建议把固定型号长期写死在教程或业务代码中。

第二步：完成最小文本请求

export MODEL_ID="从模型列表复制的真实_ID"

curl --fail-with-body --silent --show-error \
  https://www.aifast.club/v1/chat/completions \
  -H "Authorization: Bearer $AIFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL_ID"'",
    "messages": [
      {"role": "user", "content": "只回复 GEMINI_API_READY"}
    ],
    "temperature": 0
  }'

检查状态码、choices、响应 model、usage 和请求 ID。保存脱敏后的原始响应，后续排查模型路由和账单时会更有价值。

第三步：使用 Python SDK

python -m pip install --upgrade openai

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AIFAST_API_KEY"],
    base_url="https://www.aifast.club/v1",
)

response = client.chat.completions.create(
    model=os.environ["MODEL_ID"],
    messages=[
        {"role": "user", "content": "把以下会议记录整理成待办事项。"}
    ],
)

print(response.choices[0].message.content)

将 Base URL、Key 和模型 ID 分别放入配置中心。这样可以在模型维护、额度变化或业务回滚时切换配置，而不必修改代码并重新发布。

多模态能力如何验收

文本请求成功后，按业务顺序逐项验证：

1. 确认当前模型明确支持图像输入，而不是根据“Gemini”名称推断。
2. 使用一张不含隐私的测试图片，验证图片格式、大小和 URL 或 Base64 输入方式。
3. 设计有唯一答案的视觉题，例如读取随机编号或对照表格字段。
4. 记录失败状态码、错误正文、输入 Token 和完整任务成本。
5. 分别测试单图、多图和长文本组合，不用一次结果代表全部场景。

如果只需要生图或视频生成，应查看生图 API 接入和视频生成 API 接入，不要把聊天模型与生成媒体端点混为一类。

流式与稳定性验证

使用 stream=true 和 curl -N 检查 SSE：

curl -N --fail-with-body \
  https://www.aifast.club/v1/chat/completions \
  -H "Authorization: Bearer $AIFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL_ID"'",
    "messages": [{"role": "user", "content": "分五步说明接口验收流程"}],
    "stream": true
  }'

至少在不同时间段重复测试，记录成功率、P50、P95、429 和 5xx 分布。不要把单次最快延迟当作长期承诺。

常见问题

model not found

重新查询 /v1/models 并复制真实 id。不要使用网页标题、模型系列名或旧教程中的固定 ID。

返回 HTML 而不是 JSON

通常是 Base URL、路径或反向代理配置错误。检查最终 URL 是否进入 /v1/models 或 /v1/chat/completions，以及是否出现 /v1/v1。

图像输入失败

先确认模型和端点是否支持该输入类型，再核对 MIME 类型、图片大小和消息结构。文本接口成功不能证明多模态一定兼容。

输出质量波动

固定模型、参数和题集做多轮对照，并保存响应模型、Token 和时间。可以使用模型 API 对比模板避免凭一次主观感受下结论。

下一步

先运行免费模型检测检查协议和基础能力，再阅读模型降智检测方法与生产上线检查清单。黑盒检测只能提供风险信号，不是 Google 或模型厂商认证。