Gemini SDK

Use Google Gen AI Python or TypeScript SDK to call the AGTCloud Gemini Generate Content compatible interface.

The Google Gen AI SDK provides Python and TypeScript clients. Through custom HTTP configuration in the SDK, Generate Content requests can be sent to AGTCloud's Gemini-compatible portal.

This page only covers generateContent and streamGenerateContent. Whether files, caches, Live API, model management, and other Google platform resources are available should be determined by the AGTCloud API Reference.

Preparation

Before you start, please confirm that you have:

Create the AGTCloud API Key on the API Keys page;
Copy the full ID of a model that supports Gemini Generate Content from the Model Marketplace;
Prepare a supported server runtime. The current @google/genai 2.x release requires Node.js 20+; recheck the runtime requirements before a major-version upgrade.

This page uses MODEL_ID and your-api-key as placeholders. Do not store a real API Key in browser code, client packages, or public repositories.

Install the SDK

python -m pip install google-genai

Use a current stable version of google-genai or @google/genai. This guide requires support for custom base URLs, API versions, and request headers. If the constructor does not recognize http_options or httpOptions, upgrade the SDK first.

Configure the API Key

Save the API Key to the server environment variable:

export AGTCLOUD_API_KEY="your-api-key"

AGTCloud's Gemini-compatible endpoint uses Bearer authentication. The client configuration below preserves the Google Gen AI SDK request structure and explicitly adds an Authorization: Bearer ... header.

The Google Gen AI SDK still requires api_key or apiKey during initialization, so it also sends x-goog-api-key. This SDK-generated header does not replace the Bearer header required by AGTCloud.

Create a client and send a request

Use the API Origin shown on this page as the Base URL. Do not append /v1, /v1beta, or a full endpoint. The SDK combines api_version or apiVersion with the model method to build /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="Please introduce yourself in three sentences.",
)

print(response.text)

This is AGTCloud's compatible access configuration

The general API Key process for Google Gemini API is different from AGTCloud Bearer authentication. Here, you can set AGTCloud API Origin, v1beta version, and Authorization Header using custom HTTP options provided by the official SDK, and these configurations should not be omitted.

First, verify the compatibility of the current SDK and the gateway's header

The official SDK sends both Authorization and x-goog-api-key. If a minimal text request returns an authentication or header-validation error, do not remove the Bearer header or copy the real key into another field. First verify the request with the HTTP example in Gemini Generate Content API Reference, then use the SDK only after confirming that the current SDK version is compatible with the gateway.

Streaming output

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="Please briefly explain what vector retrieval is.",
):
    if chunk.text:
        print(chunk.text, end="", flush=True)

The streaming method continuously returns Generate Content response chunks. The production environment should handle connection interruptions, timeouts, blank text blocks, and requests not ending properly.

Frequently Asked Questions

Issue	What to check
`401` or `403`	Confirm that `AGTCLOUD_API_KEY` is loaded, the custom headers include `Authorization: Bearer ...`, and the current gateway accepts the SDK-generated `x-goog-api-key`
`404` or a duplicated version segment in the path	Set the Base URL to `https://api.agtcloud.cn` and the API version to `v1beta`
The constructor does not recognize the HTTP configuration	Upgrade `google-genai` or `@google/genai` to a current stable version
The model is unavailable	Replace `MODEL_ID` with the model ID available to the current API Key that supports Gemini Generate Content
The response structure differs from expectations	Inspect `candidates`, `content`, and `parts`; do not rely only on the aggregated `response.text` value
Ordinary texts succeed, but advanced abilities fail	Check whether the target model supports the corresponding Parts, tool calls, or multimodal inputs

Do not assume the custom gateway supports every SDK resource

This page covers only Generate Content and streaming generation. Do not assume that file uploads, caching, Live APIs, model listing, or other Google platform methods in the SDK work through the same address. For available AGTCloud resources, see the API Reference.

See Gemini Generate Content API Reference to learn about contents, parts, generation configuration, and complete response structure.
See Gemini Stream Generate Content API Reference to learn about streaming endpoints and response events.
For existing original SDK projects, you can refer to Provider SDK Migration to replace configurations item by item and regress for testing.
If the request fails, refer to Authentication and API Key and Error and Troubleshooting.