Gemini API 참조

이 API 참조에서는 Gemini 모델과 상호작용하는 데 사용할 수 있는 단항, 스트리밍, 실시간 API를 설명합니다. HTTP 요청을 지원하는 모든 환경에서 REST API를 사용할 수 있습니다. 첫 번째 API 호출을 시작하는 방법은 시작 가이드를 참고하세요. 언어별 라이브러리 및 SDK 참조를 찾고 있다면 왼쪽 탐색의 SDK 참조에서 해당 언어의 링크를 클릭하세요.

기본 엔드포인트

Gemini API는 다음과 같은 주요 엔드포인트를 중심으로 구성됩니다.

• 상호작용 (CreateInteraction) (권장): Gemini로 빌드하는 데 권장되는 표준 기본 요소로, 에이전트 워크플로, 서버 측 상태 관리, 복잡한 멀티모달, 멀티턴 대화에 최적화되어 있습니다.
• 표준 콘텐츠 생성 (generateContent): 요청을 처리하고 모델의 전체 응답을 단일 패키지로 반환하는 표준 REST 엔드포인트입니다. 전체 결과를 기다릴 수 있는 비대화형 작업에 가장 적합합니다.
• 스트리밍 콘텐츠 생성 (streamGenerateContent): 서버 전송 이벤트 (SSE)를 사용하여 대답 청크를 생성되는 대로 푸시합니다. 이를 통해 챗봇과 같은 애플리케이션에 더 빠르고 상호작용적인 환경을 제공할 수 있습니다.
• Live API (BidiGenerateContent): 실시간 대화 사용 사례를 위해 설계된 양방향 스트리밍용 스테이트풀 WebSocket 기반 API입니다.
• 일괄 모드 (batchGenerateContent): generateContent 요청 일괄 처리를 제출하기 위한 표준 REST 엔드포인트입니다.
• 임베딩 (embedContent): 입력 Content에서 텍스트 임베딩 벡터를 생성하는 표준 REST 엔드포인트입니다.
• 생성 미디어 API: 이미지 생성용 Imagen 및 동영상 생성용 Veo와 같은 전문 모델로 미디어를 생성하는 엔드포인트입니다. Gemini에는 이러한 기능이 내장되어 있으며 generateContent API를 사용하여 액세스할 수 있습니다.
• 플랫폼 API: 파일 업로드, 토큰 수 세기와 같은 핵심 기능을 지원하는 유틸리티 엔드포인트입니다.

인증

Gemini API에 대한 모든 요청에는 API 키가 포함된 x-goog-api-key 헤더가 포함되어야 합니다. Google AI Studio에서 몇 번의 클릭으로 만들 수 있습니다.

다음은 헤더에 API 키가 포함된 요청의 예입니다.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

Gemini SDK를 사용하여 API에 키를 전달하는 방법에 관한 안내는 Gemini API 키 사용 가이드를 참고하세요.