Skip to main content
POST
Gemini 네이티브 형식

소개

Gemini Native API는 Google Gemini의 요청 및 응답 형식을 사용합니다. Google 공식 클라이언트(예: google-generativeai SDK) 또는 Gemini 데이터 구조를 직접 다루어야 할 때 적합합니다. API는 Gemini 사양을 따르며 사고 모드, 멀티모달 입력, 도구 호출, Google Search(Grounding), 컨텍스트 캐싱, 이미지 생성 등 전체 기능을 지원합니다.
OpenAI 호환 클라이언트(예: OpenAI SDK)로 Gemini를 사용하는 경우 Gemini OpenAI 형식(Chat)을 참조하세요. 다른 모델은 OpenAI Chat Completions를 사용하세요.

OpenAI 형식과의 차이

API 엔드포인트

경로의 {model}을 실제 모델 ID(예: gemini-2.5-pro, gemini-3-pro-preview)로 바꿉니다.

인증

다음 중 하나를 사용할 수 있습니다:
string
Bearer 토큰: Bearer sk-xxxxxxxxxx (권장, 다른 GravitexAI 엔드포인트와 동일)
string
Google 스타일 API 키: x-goog-api-key: sk-xxxxxxxxxx
URL에 키를 전달할 수도 있습니다: ?key=sk-xxxxxxxxxx.

요청 매개변수

generateContent / streamGenerateContent

array
필수
대화 내용 목록. 각 항목은 role(user 또는 model)과 parts를 가집니다. 각 part는 {"text": "..."}, {"inlineData": {"mimeType": "...", "data": "base64..."}}, 또는 {"fileData": {"mimeType": "...", "fileUri": "gs://..."}}일 수 있습니다.
object
생성 설정.
  • temperature: 0–2, 무작위성
  • topP: nucleus 샘플링
  • topK: top-K 샘플링
  • maxOutputTokens: 최대 출력 토큰 수
  • stopSequences: 중지 시퀀스
  • responseMimeType: 예: text/plain
  • responseModalities: 예: ["TEXT"] 또는 ["IMAGE"]
  • thinkingConfig: 사고 모드(아래 참조)
  • imageConfig: 이미지 생성 설정(아래 참조)
object
시스템 지시: {"parts": [{"text": "..."}]}.
array
안전 수준, 예: [{"category": "HARM_CATEGORY_HARASSMENT", "threshold": "OFF"}].
array
도구 선언(function calling), 고급 기능 참조.
object
도구 설정, 예: functionCallingConfig.mode: AUTO / ANY / NONE.
string
API가 반환한 컨텍스트 캐싱 ID; 캐시된 컨텍스트 재사용에 사용.

응답 형식

비스트리밍 generateContent는 JSON을 반환합니다:
스트리밍 엔드포인트는 SSE를 반환합니다. 각 줄은 data: 로 시작하며 JSON 조각(예: candidates[].content.parts)을 포함합니다.

기본 예시

기본적으로 google-generativeai는 Google API를 호출합니다. GravitexAI를 사용하려면 client_options 또는 환경 변수를 통해 api_endpointhttps://api.gravitex.ai로 설정하세요. 자세한 내용은 SDK 문서를 참조하세요.

고급 기능

사고 모드

세 가지 방식으로 지원됩니다:
  1. generationConfig.thinkingConfig (Gemini 2.5 Pro): thinkingBudget(토큰 수) 사용
  2. thinkingConfig.thinkingLevel (Gemini 3 Pro): LOW / HIGH 사용
  3. 모델 접미사: -thinking, -thinking-8192, -nothinking, -thinking-low, -thinking-high

멀티모달 입력

contents[].parts에서 텍스트와 미디어를 혼합할 수 있습니다:
  • 이미지: base64 data가 있는 inlineData, 또는 fileUri(예: gs://...)가 있는 fileData
  • 오디오: audio/mp3 등의 mimeType이 있는 inlineData

도구 호출(Function Calling)

모델이 functionCall part를 반환할 수 있습니다. 다음 contents에 해당 functionResponse를 포함하여 다시 요청하세요.

Google Search(Grounding)

활성화하면 모델이 실시간 웹 검색을 사용하여 답변을 개선할 수 있습니다(예: 날씨, 뉴스). toolsgoogleSearch를 추가하세요:
function calling과 Google Search를 함께 사용하려면 동일한 tools 배열에 googleSearch: {}functionDeclarations를 별도 요소로 포함하세요. 응답에 검색 메타데이터(예: groundingMetadata)가 포함될 수 있습니다.

스트리밍

사용: POST /v1beta/models/{model}:streamGenerateContent?alt=sse. 요청 본문은 generateContent와 동일합니다. 응답은 SSE이며, 각 data: 줄이 JSON 청크입니다.

컨텍스트 캐싱

첫 요청에는 cachedContent를 포함하지 않습니다. 서버가 캐시 ID를 반환하면 이후 요청에서 다음과 같이 전송할 수 있습니다:
긴 반복 컨텍스트의 비용과 지연 시간을 줄일 수 있습니다.

이미지 생성(예: Gemini 2.5 Flash)

모델이 이미지 출력을 지원할 때 generationConfig에서 설정:
응답 candidates[].content.partsinlineData(예: base64 이미지)가 포함될 수 있습니다.

Embedding API

단일: embedContent

엔드포인트: POST https://api.gravitex.ai/v1beta/models/{model}:embedContent 요청 본문 예시:
또는 경로에 model을 넣습니다: /v1beta/models/text-embedding-004:embedContent, 본문에는 content만 포함.

일괄: batchEmbedContents

엔드포인트: POST https://api.gravitex.ai/v1beta/models/{model}:batchEmbedContents 요청 본문 예시:
응답은 요청당 하나의 임베딩이 포함된 배열입니다.

오류 처리

오류는 HTTP 상태 코드와 JSON 본문으로 반환됩니다:
일반적인 경우: 클라이언트에서 error.message를 파싱하고 재시도 또는 사용자 메시지를 적절히 처리하세요.

OpenAI 형식과의 비교

Google Gemini 도구에 의존하거나 Gemini 전용 필드(예: thinkingConfig, 네이티브 멀티모달 parts)가 필요할 때 네이티브 엔드포인트를 사용하세요. OpenAI 생태계 내에서 작업하려면 /v1/chat/completions를 사용하세요.