이제 Gemini API에서 Gemini 2.5 Flash Image (일명 Nano Banana)를 사용할 수 있습니다. 자세히 알아보기

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Gemini API reference

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

기본 엔드포인트

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

표준 콘텐츠 생성 (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-2.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 키 사용 가이드를 참고하세요.

콘텐츠 생성

모델에 프롬프트를 전송하는 중앙 엔드포인트입니다. 콘텐츠를 생성하는 데는 두 가지 엔드포인트가 있으며, 주요 차이점은 응답을 수신하는 방식입니다.

generateContent(REST): 요청을 수신하고 모델이 전체 생성을 완료한 후 단일 응답을 제공합니다.
streamGenerateContent(SSE): 정확히 동일한 요청을 수신하지만 모델은 응답 청크를 생성되는 대로 스트리밍합니다. 이렇게 하면 부분 결과를 즉시 표시할 수 있으므로 대화형 애플리케이션의 사용자 환경이 개선됩니다.

요청 본문 구조

요청 본문은 표준 모드와 스트리밍 모드 모두에서 동일하며 몇 가지 핵심 객체에서 빌드되는 JSON 객체입니다.

Content 객체: 대화의 단일 턴을 나타냅니다.
Part 객체: Content 턴 내의 데이터 조각(예: 텍스트 또는 이미지)입니다.
inline_data (Blob): 원시 미디어 바이트와 MIME 유형의 컨테이너입니다.

최상위 수준에서 요청 본문에는 contents 객체가 포함됩니다. 이 객체는 Content 객체의 목록이며, 각 객체는 대화의 턴을 나타냅니다. 대부분의 경우 기본 텍스트 생성에는 단일 Content 객체가 사용되지만, 대화 기록을 유지하려면 여러 Content 객체를 사용할 수 있습니다.

다음은 일반적인 generateContent 요청 본문을 보여줍니다.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
          "role": "user",
          "parts": [
              // A list of Part objects goes here
          ]
      },
      {
          "role": "model",
          "parts": [
              // A list of Part objects goes here
          ]
      }
    ]
  }'

응답 본문 구조

응답 본문은 스트리밍 모드와 표준 모드 모두에서 비슷하지만 다음 사항은 다릅니다.

표준 모드: 응답 본문에 GenerateContentResponse 인스턴스가 포함됩니다.
스트리밍 모드: 응답 본문에는 GenerateContentResponse 인스턴스 스트림이 포함됩니다.

개략적으로 응답 본문에는 Candidate 객체 목록인 candidates 객체가 포함됩니다. Candidate 객체에는 모델에서 반환된 생성된 대답이 있는 Content 객체가 포함됩니다.

요청 예시

다음 예에서는 다양한 유형의 요청에 대해 이러한 구성요소가 어떻게 결합되는지 보여줍니다.

텍스트 전용 프롬프트

간단한 텍스트 프롬프트는 단일 Content 객체가 있는 contents 배열로 구성됩니다. 이 객체의 parts 배열에는 text 필드가 있는 단일 Part 객체가 포함됩니다.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.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 single paragraph."
          }
        ]
      }
    ]
  }'

멀티모달 프롬프트 (텍스트 및 이미지)

프롬프트에 텍스트와 이미지를 모두 제공하려면 parts 배열에 Part 객체 두 개가 포함되어야 합니다. 하나는 텍스트용이고 다른 하나는 이미지 inline_data용입니다.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
    "contents": [{
    "parts":[
        {
            "inline_data": {
            "mime_type":"image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ... (base64-encoded image)"
            }
        },
        {"text": "What is in this picture?"},
      ]
    }]
  }'

멀티턴 대화 (채팅)

턴이 여러 개인 대화를 빌드하려면 Content 객체가 여러 개인 contents 배열을 정의합니다. API는 이 전체 기록을 다음 응답의 컨텍스트로 사용합니다. 각 Content 객체의 role은 user와 model 사이에서 번갈아 표시되어야 합니다.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Hello." }
        ]
      },
      {
        "role": "model",
        "parts": [
          { "text": "Hello! How can I help you today?" }
        ]
      },
      {
        "role": "user",
        "parts": [
          { "text": "Please write a four-line poem about the ocean." }
        ]
      }
    ]
  }'

핵심 내용

Content는 봉투입니다. 사용자 또는 모델에서 온 메시지 턴의 최상위 컨테이너입니다.
Part를 사용하면 멀티모달리티를 지원할 수 있습니다. 단일 Content 객체 내에서 여러 Part 객체를 사용하여 다양한 유형의 데이터 (텍스트, 이미지, 동영상 URI 등)를 결합합니다.
데이터 방법을 선택합니다.
- 대부분의 이미지와 같이 직접 삽입된 작은 미디어의 경우 inline_data와 함께 Part를 사용합니다.
- 대용량 파일 또는 요청 간에 재사용하려는 파일의 경우 File API를 사용하여 파일을 업로드하고 file_data 파트로 참조하세요.
대화 기록 관리: REST API를 사용하는 채팅 애플리케이션의 경우 각 턴에 Content 객체를 추가하여 contents 배열을 빌드하고 "user" 역할과 "model" 역할을 번갈아 사용합니다. SDK를 사용하는 경우 대화 기록을 관리하는 권장 방법은 SDK 문서를 참고하세요.

응답 예시

다음 예에서는 다양한 유형의 요청에 대해 이러한 구성요소가 어떻게 결합되는지 보여줍니다.

텍스트 전용 응답

간단한 텍스트 대답은 모델의 대답을 포함하는 하나 이상의 content 객체가 있는 candidates 배열로 구성됩니다.

다음은 표준 응답의 예입니다.

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "At its core, Artificial Intelligence works by learning from vast amounts of data ..."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 1
    }
  ],
}

다음은 일련의 스트리밍 응답입니다. 각 응답에는 전체 응답을 연결하는 responseId이 포함됩니다.

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "The image displays"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  },
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

...

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": " the following materials:\n\n*   **Wood:** The accordion and the violin are primarily"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  }
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

Live API (BidiGenerateContent) WebSockets API

Live API는 실시간 스트리밍 사용 사례를 지원하기 위해 양방향 스트리밍을 위한 스테이트풀 WebSocket 기반 API를 제공합니다. 자세한 내용은 Live API 가이드 및 Live API 참조를 확인하세요.

특화 모델

Gemini API는 Gemini 모델 제품군 외에도 Imagen, Lyria, embedding 모델과 같은 전문 모델을 위한 엔드포인트를 제공합니다. 모델 섹션에서 이러한 가이드를 확인할 수 있습니다.

플랫폼 API

나머지 엔드포인트는 지금까지 설명한 기본 엔드포인트와 함께 사용할 수 있는 추가 기능을 지원합니다. 자세한 내용은 가이드 섹션의 일괄 모드 및 파일 API 주제를 참고하세요.

다음 단계

이제 막 시작하는 경우 Gemini API 프로그래밍 모델을 이해하는 데 도움이 되는 다음 가이드를 확인하세요.

다양한 Gemini API 기능을 소개하고 코드 예시를 제공하는 기능 가이드를 확인해 보세요.