Gemini API 연동 가이드: Google 호환 호출 및 초대형 컨텍스트

1. 개요

본 사이트는 Google Gemini API 호환 연동을 제공하며, generateContent 및 스트리밍 생성 호출 방식을 모두 지원합니다. Google GenAI SDK 또는 Gemini 호환 클라이언트를 사용하는 프로젝트의 경우, 요청 주소를 본 사이트 게이트웨이의 Gemini 엔드포인트로 설정하고 API 키를 본 사이트의 sk- 키로 교체하면 즉시 연동 가능합니다.

현재 사용 가능한 Gemini 시리즈 모델은 모델 광장(Model Plaza)을 기준으로 합니다(예: gemini-3.7-flash, gemini-3.6-flash, gemini-3.5-flash, gemini-3.5-flash-lite 등). 전체 모델 목록 및 단가는 GET /v1/models를 통해 조회할 수 있습니다.

2. 인터페이스 주소

메서드	경로	설명
POST	/v1beta/models/{model}:generateContent	Gemini 생성 엔드포인트, 요청 본문은 generateContent 페이로드
POST	/v1beta/models/{model}:streamGenerateContent?alt=sse	스트리밍 생성 (SSE)
GET	/v1/models	모델 및 단가 목록 (인증 불필요)

게이트웨이 주소: https://www.relay-api.com. 모델명은 URL에 붙입니다(/v1beta/models/{model}:generateContent, Google 공식 규격과 동일). 요청 본문은 generateContent 페이로드입니다.

3. 인증 방식

본 사이트의 다른 인터페이스와 동일하게 사이트 내 sk- 키를 사용합니다:

Authorization: Bearer sk-당신의_키

x-api-key 헤더와 Google 공식 x-goog-api-key: sk-당신의_키 헤더도 호환됩니다.

4. 빠른 시작 (curl)

4.1 비스트리밍

curl -X POST https://www.relay-api.com/v1beta/models/gemini-3.7-flash:generateContent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-당신의_키" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "Gemini API를 한 문장으로 소개해주세요."}]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 512
    }
  }'

4.2 시스템 지침 포함 (systemInstruction)

curl -X POST https://www.relay-api.com/v1beta/models/gemini-3.7-flash:generateContent \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-당신의_키" \
  -d '{
    "model": "gemini-3.5-flash",
    "systemInstruction": {
      "parts": [{"text": "당신은 숙련된 API 통합 엔지니어입니다. 간결하게 답변하세요."}]
    },
    "contents": [
      {"role": "user", "parts": [{"text": "스트리밍 인터페이스와 비스트리밍 인터페이스는 어떻게 선택하나요?"}]}
    ]
  }'

5. 요청 매개변수

필드	타입	필수	설명
model	string	예	모델 슬러그 (예: gemini-3.7-flash)
contents	array	예	대화 내용, 요소는 {role, parts[]}; role 값은 user / model
contents[].parts	array	예	콘텐츠 블록, 주로 {text} 텍스트 블록 사용
systemInstruction	object	아니오	시스템 지침, 구조 {parts: [{text}]}
generationConfig.temperature	number	아니오	샘플링 온도, 기본값 1.0
generationConfig.topP	number	아니오	핵 샘플링 (Nucleus sampling)
generationConfig.topK	int	아니오	Top-K 샘플링
generationConfig.maxOutputTokens	int	아니오	최대 출력 토큰 수
generationConfig.stopSequences	array	아니오	정지 시퀀스
stream	bool	아니오	스트리밍 반환 여부, 기본값 false

6. 응답 구조

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{"text": "Gemini API는 텍스트, 멀티모달 입력 및 스트리밍 출력을 지원합니다."}]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 16,
    "candidatesTokenCount": 20,
    "totalTokenCount": 36
  }
}

필드	설명
candidates[].content.parts[].text	모델이 생성한 텍스트
candidates[].finishReason	종료 사유: STOP / MAX_TOKENS / SAFETY / RECITATION
usageMetadata.promptTokenCount	입력 토큰 수 (과금 기준)
usageMetadata.candidatesTokenCount	출력 토큰 수 (과금 기준)
usageMetadata.totalTokenCount	총 토큰 수

7. 스트리밍 출력

요청 본문에 "stream": true를 추가하면, 서버가 SSE 방식으로 후보 콘텐츠를 블록 단위로 반환합니다:

data: {"candidates": [{"content": {"parts": [{"text": "Gemini"}]}, "index": 0}]}

data: {"candidates": [{"content": {"parts": [{"text": " API는 스트리밍"}]}, "index": 0}]}

data: {"candidates": [{"content": {"parts": [{"text": "출력을 지원합니다."}]}, "index": 0, "finishReason": "STOP"}]}

클라이언트는 각 data: 라인을 파싱하여 candidates[0].content.parts[0].text를 이어 붙입니다. 마지막 청크의 finishReason이 STOP이면 생성이 완료된 것입니다.

8. 일반적인 오류 코드

HTTP 상태 코드	의미	처리 제안
400	요청 형식 오류 (contents 누락, 모델 없음 등)	요청 본문 및 모델명 확인
401	유효하지 않거나 누락된 API 키	Authorization / x-api-key 헤더 확인
403	키 정지, 잔액 부족 또는 해당 모델/경로 미승인	충전 또는 키 권한 확인
404	모델 또는 엔드포인트 존재하지 않음	모델 슬러그 확인
429	요청 너무 잦음 (Rate limit 초과)	백오프(Back-off) 후 재시도
500	서버 내부 오류	잠시 후 재시도, 지속 발생 시 고객센터 문의

오류 응답 본문은 항상 {"code": 상태코드, "message": "오류 설명", "data": null} 구조입니다.

9. 호환성 참고사항

• Google GenAI SDK(google-genai)는 사용자 정의 엔드포인트를 통해 연동 가능합니다.
• generateContent를 대상으로 하는 다양한 Gemini 호환 클라이언트를 지원합니다.
• 모델명은 GET /v1/models에서 반환되는 슬러그를 기준으로 합니다.

Base URL 설명: 본 사이트는 /v1beta/models/... 및 /v1beta/v1beta/models/... (그리고 /v1/... 및 /v1/v1/...)을 모두 허용하므로, 클라이언트가 /v1이나 /v1beta를 자동으로 추가하더라도 호출에 영향이 없습니다. Base URL은 도메인 루트 또는 /v1beta가 포함된 주소 모두 사용 가능합니다. 모델 ID는 제어판의 '토큰' 페이지 우측 상단의 '모델 ID'에서 조회 및 복사하십시오.