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-당신의_API_키

또한 x-api-key 헤더나 Google 공식 x-goog-api-key: sk-당신의_API_키 헤더도 호환됩니다.

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-당신의_API_키" \
  -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-당신의_API_키" \
  -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)	잠시 후 다시 시도
500	서버 내부 오류	잠시 후 재시도, 지속 발생 시 고객센터 문의

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

9. 호환성 안내

• Google GenAI SDK (google-genai)는 엔드포인트 커스텀 설정을 통해 연동 가능합니다.
• generateContent를 목표로 하는 모든 Gemini 호환 클라이언트를 지원합니다.
• 모델 이름은 GET /v1/models 결과값의 슬러그(slug)를 기준으로 합니다.