Gemini SDK

Google Gen AIのPythonまたはTypeScript SDKから、AGTCloudのGemini Generate Content互換APIを呼び出します。

Google Gen AI SDK は、Python と TypeScript のクライアントを提供します。SDK の HTTP 設定をカスタマイズすると、コンテンツ生成リクエストを AGTCloud の Gemini 互換エンドポイントに送信できます。

このページでは、generateContent と streamGenerateContent のみを説明します。ファイル、キャッシュ、ライブ 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 を使用してください。このチュートリアルでは、カスタム Base URL、API バージョン、およびリクエストヘッダーをサポートする SDK が必要です。コンストラクターが次の http_options / httpOptions を認識しない場合は、最初に SDK をアップグレードしてください。

API Keyを設定する

API Keyをサーバー環境変数に保存します。

export AGTCLOUD_API_KEY="your-api-key"

AGTCloud の Gemini 互換エンドポイントはベアラー API Keyを使用します。次のクライアント設定では、Google Gen AI SDK リクエスト構造が保持され、Authorization: Bearer ... ヘッダーが明示的に追加されます。

Google Gen AI SDK の初期化には api_key / apiKey が必要なため、SDK は x-goog-api-key ヘッダーも送信します。このヘッダーは SDK が付加するもので、AGTCloud の認証に使用する Bearer ヘッダーの代わりにはなりません。

クライアントを作成してリクエストを送信する

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="自己紹介を3文でお願いします。",
)

print(response.text)

これは AGTCloud と互換性のある接続設定です。

Google Gemini API の通常の API Key プロセスは、AGTCloud Bearer 認証とは異なります。ここで、AGTCloud API Origin、v1beta バージョン、および Authorization ヘッダーは、公式 SDK によって提供されるカスタム HTTP オプションを通じて設定されます。これらの設定は省略しないでください。

まず、現在の SDK とゲートウェイのヘッダー互換性を確認します。

公式 SDK は Authorization と x-goog-api-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` がロードされていること、カスタムヘッダーに `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 コンテンツの生成をサポートするモデルID に置き換えます。
戻り値の構造が予想とは異なります	`candidates`、`content`、`parts` を確認し、集約された `response.text` だけに依存しないでください。
通常のテキストは成功しますが、高度な能力は失敗します	対象モデルが対応するパーツ、ツール呼び出し、またはマルチモーダル入力をサポートしているかどうかを確認します。

カスタムゲートウェイ機能を他の SDK リソースに拡張しないでください。

このページでは、コンテンツの生成とストリーミングの生成についてのみ説明します。 SDK 内のファイルのアップロード、キャッシュ、ライブ API、モデルリスト、またはその他の Google プラットフォームメソッドがすべて同じアドレスを通じて機能するとは想定しないでください。他のリソースの利用可能性については、AGTCloud API Referenceを参照してください。

次のステップ

contents、parts、生成設定、および完全な応答構造については、Gemini Generate Content API Reference を参照してください。
ストリーミングエンドポイントと応答イベントの詳細については、「Gemini Stream Generate Content API Reference」を参照してください。
既存の公式 SDK プロジェクトがある場合は、公式 SDK からの移行を参照し、設定項目を一つずつ置き換えて回帰テストを実施してください。
リクエストが失敗した場合は、認証と API Key、エラーとトラブルシューティングを参照してください。