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 초기화를 요구하므로 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와 오류 및 문제 해결을 참고합니다.