Gemini SDK

使用 Google Gen AI Python 或 TypeScript SDK 调用 AGTCloud Gemini Generate Content 兼容接口。

Google Gen AI SDK 提供 Python 和 TypeScript 客户端。通过 SDK 的自定义 HTTP 配置，可以将 Generate Content 请求发送到 AGTCloud 的 Gemini 兼容入口。

本页只覆盖 generateContent 与 streamGenerateContent。文件、缓存、Live API、模型管理及其他 Google 平台资源是否可用，应以 AGTCloud API Reference 为准。

准备工作

开始前，请确认你已经：

在 API Keys 页面创建 AGTCloud API Key；
从模型广场复制支持 Gemini Generate Content 的完整模型 ID；
准备受支持的服务端运行环境。当前 @google/genai 2.x 要求 Node.js 20+；升级主版本前请重新核对运行环境要求。

本页使用 MODEL_ID 和 your-api-key 作为占位符。请勿在浏览器、客户端安装包或公开仓库中保存真实 API Key。

安装 SDK

python -m pip install google-genai

请使用当前稳定版 google-genai 或 @google/genai。本教程需要 SDK 支持自定义 Base URL、API 版本和请求 Header；如果构造函数不识别下文的 http_options / httpOptions，请先升级 SDK。

配置 API Key

将 API Key 保存到服务端环境变量：

export AGTCLOUD_API_KEY="your-api-key"

AGTCloud 的 Gemini 兼容入口使用 Bearer API Key。下面的客户端配置会保留 Google Gen AI SDK 的请求结构，并显式添加 Authorization: Bearer ... Header。

Google Gen AI SDK 仍要求初始化 api_key / apiKey，因此 SDK 还会附带 x-goog-api-key。该 Header 来自 SDK，不替代 AGTCloud 使用的 Bearer Header。

创建客户端并发送请求

Base URL 使用本页显示的 API Origin，不要追加 /v1、/v1beta 或完整业务路径。SDK 会根据 api_version / apiVersion 与模型方法拼接 /v1beta/models/{model}:generateContent。

import os

from google import genai
from google.genai import types

api_key = os.environ["AGTCLOUD_API_KEY"]

client = genai.Client(
    api_key=api_key,
    http_options=types.HttpOptions(
        base_url="https://api.agtcloud.cn",
        api_version="v1beta",
        headers={"Authorization": f"Bearer {api_key}"},
    ),
)

response = client.models.generate_content(
    model="MODEL_ID",
    contents="请用三句话介绍你自己。",
)

print(response.text)

这是 AGTCloud 的兼容接入配置

Google Gemini API 的常规 API Key 流程与 AGTCloud Bearer 鉴权不同。这里通过官方 SDK 提供的自定义 HTTP 选项设置 AGTCloud API Origin、v1beta 版本和 Authorization Header，不应省略这些配置。

先验证当前 SDK 与网关的 Header 兼容性

官方 SDK 会同时发送 Authorization 和 x-goog-api-key。如果最小文本请求返回鉴权或 Header 校验错误，请不要删除 Bearer Header，也不要把真实 Key 写入其他字段；可先使用 Gemini Generate Content API Reference 中的 HTTP 调用方式，并在确认当前 SDK 与网关兼容后再切换。

流式输出

import os

from google import genai
from google.genai import types

api_key = os.environ["AGTCLOUD_API_KEY"]

client = genai.Client(
    api_key=api_key,
    http_options=types.HttpOptions(
        base_url="https://api.agtcloud.cn",
        api_version="v1beta",
        headers={"Authorization": f"Bearer {api_key}"},
    ),
)

for chunk in client.models.generate_content_stream(
    model="MODEL_ID",
    contents="请简要解释什么是向量检索。",
):
    if chunk.text:
        print(chunk.text, end="", flush=True)

流式方法会持续返回 Generate Content 响应分块。生产环境应处理连接中断、超时、空文本块和请求未正常结束等情况。

常见问题

现象	检查项
`401` 或 `403`	确认 `AGTCLOUD_API_KEY` 已加载、自定义 Header 包含 `Authorization: Bearer ...`，并检查当前网关是否接受 SDK 附带的 `x-goog-api-key`
`404` 或路径包含重复版本	Base URL 只填写 `https://api.agtcloud.cn`，并把 API 版本设置为 `v1beta`
构造函数不识别 HTTP 配置	升级至当前稳定版 `google-genai` 或 `@google/genai`
模型不可用	将 `MODEL_ID` 替换为当前 API Key 可见且支持 Gemini Generate Content 的模型 ID
返回结构与预期不同	核对 `candidates`、`content` 和 `parts`，不要只依赖聚合后的 `response.text`
普通文本成功但高级能力失败	核对目标模型是否支持相应的 Parts、工具调用或多模态输入

不要把自定义 Gateway 能力扩大到其他 SDK 资源

本页仅覆盖 Generate Content 与流式生成。不要据此假设 SDK 中的文件上传、缓存、Live API、模型列表或其他 Google 平台方法都会通过相同地址工作；其他资源是否可用，请以 AGTCloud API Reference 为准。

下一步

查看 Gemini Generate Content API Reference了解 contents、parts、生成配置和完整响应结构。
查看 Gemini Stream Generate Content API Reference了解流式端点与响应事件。
已有原厂 SDK 项目可以参考原厂 SDK 迁移逐项替换配置并回归测试。
请求失败时，参阅认证与 API Key和错误与排障。