Gemini 시리즈

Google의 Gemini 텍스트 모델로, Gemini 3.x 시리즈가 중심입니다. Gemini 네이티브 API(공식 google-genai SDK를 바로 사용 가능)와 OpenAI 호환 API 두 가지 방식으로 호출할 수 있습니다.

주요 작업

사고 조절 사고는 기본적으로 켜져 있으며, 시간이 오래 걸릴 때 사고량을 줄이는 방법.Google 검색 웹에서 실시간 정보를 가져오고 출처를 반환합니다.PDF와 오디오 문서와 오디오를 업로드해 분석합니다.오류 해결 답변 잘림, 모델 서비스 종료, 컨텍스트 초과.Gemini CLI에서 사용 연동 설정과 자주 묻는 질문.

모델

텍스트, 이미지, 오디오, PDF 입력을 지원하며 컨텍스트는 약 1M 토큰입니다. 전체 모델 목록과 실시간 가격은 모델 페이지 를 참고하거나 Models API로 조회하십시오. 이미지 생성 모델은 Nano Banana를 참고하십시오.

주요 모델 ID(호출 시 그대로 복사)

Gemini 3.8 Flashgoogle/gemini-3.8-flash

Gemini 3.1 Pro Previewgoogle/gemini-3.1-pro-preview

Gemini 3.5 Flash-Litegoogle/gemini-3.5-flash-lite기본적으로 사고하지 않음, 응답이 빠름

Gemini 3.5 Flashgoogle/gemini-3.5-flash

모델 ID에서 google/ 접두사를 생략할 수 있습니다. 네이티브 API 주소에서도 접두사를 붙이거나 생략할 수 있으며, 예를 들어 models/google/gemini-3.8-flash:generateContent와 models/gemini-3.8-flash:generateContent 모두 사용할 수 있습니다.

엔드포인트 선택

요점사고를 세밀하게 제어하거나 Google 검색 출처를 받아야 할 때는 Gemini 네이티브 API를 사용하십시오.

	Gemini 네이티브 API(권장)	OpenAI 호환 API
주소	`POST https://api.ofox.ai/gemini/v1beta/models/<모델 ID>:generateContent`	`POST https://api.ofox.ai/v1/chat/completions`
SDK	`google-genai`, `base_url`은 `https://api.ofox.ai/gemini`	OpenAI SDK, `base_url`은 `https://api.ofox.ai/v1`
인증	`x-goog-api-key: <Key>`, `Authorization: Bearer <Key>`도 허용	`Authorization: Bearer <Key>`
스트리밍	`:streamGenerateContent?alt=sse`	`"stream": true`
사고	`thinkingConfig`, 사고 요약 반환 가능	`reasoning_effort` 또는 `reasoning`, `reasoning_details` 반환
Google 검색	`tools: [{"google_search": {}}]`, 출처와 검색어 반환	`web_search_options`, 답변만 반환

네이티브 API는 URL 파라미터 ?key=로 Key를 전달하는 방식을 지원하지 않으며 401이 반환됩니다. 요청 헤더를 사용하십시오.

Gemini 모델은 현재 Google Vertex AI(google_vertex)가 제공합니다. 전체 요청 파라미터는 Generate Content를 참고하십시오.

호출 예시

Python(google-genai)

gemini_basic.py


import os
from google import genai
 
client = genai.Client(
    api_key=os.environ["OFOX_API_KEY"],
    http_options={"api_version": "v1beta", "base_url": "https://api.ofox.ai/gemini"},
)
 
resp = client.models.generate_content(
    model="google/gemini-3.8-flash",
    contents="멱등성이 무엇인지 한 문장으로 설명해 주세요.",
)
print(resp.text)

cURL

Terminal


curl "https://api.ofox.ai/gemini/v1beta/models/google/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "멱등성이 무엇인지 한 문장으로 설명해 주세요."}]}]
  }'

Python(OpenAI SDK)

gemini_openai_sdk.py


import os
from openai import OpenAI
 
client = OpenAI(base_url="https://api.ofox.ai/v1", api_key=os.environ["OFOX_API_KEY"])
 
resp = client.chat.completions.create(
    model="google/gemini-3.8-flash",
    messages=[{"role": "user", "content": "멱등성이 무엇인지 한 문장으로 설명해 주세요."}],
)
print(resp.choices[0].message.content)

프롬프트 캐싱

Gemini는 자동으로 암시적 캐시를 적용합니다. 요청의 접두부가 최근 요청과 같고 충분히 길면, 적중한 부분은 캐시 읽기 단가로 과금되며 요청을 수정할 필요가 없습니다.

항목	설명
적중 확인	네이티브 API는 `usageMetadata.cachedContentTokenCount`가 0보다 큼. OpenAI 호환 API는 `usage.prompt_tokens_details.cached_tokens`가 0보다 큼
안정성	암시적 캐시는 최선형(best effort)이므로 접두부가 같은 요청도 적중하지 않을 수 있음
확정적 캐시	큰 콘텐츠를 안정적으로 재사용해야 할 때는 명시적 캐시를 사용. Gemini 명시적 캐시 참고

자주 발생하는 오류

요점답변이 중간에 잘리는 것은 대개 사고가 출력 한도를 차지했기 때문입니다. 오류가 아니므로 finishReason을 확인하십시오.

HTTP · 상태	오류 원문	원인	해결 방법
200, `finishReason: "MAX_TOKENS"`	—	사고와 답변의 총 길이가 `maxOutputTokens`에 도달해 답변이 잘림	`maxOutputTokens`를 늘리거나 `thinkingLevel: "low"`로 사고량을 줄임. OpenAI 호환 API에서는 `finish_reason: "length"`
400 `INVALID_ARGUMENT`	`The input token count exceeds the maximum number of tokens allowed 1048576.`	입력이 모델 컨텍스트를 초과함	입력을 줄임
410 `model_deprecated`	`Model 'google/gemini-3-pro-preview' is deprecated and no longer accepts requests; please switch to an active model`	프리뷰 모델이 서비스 종료됨	정식 버전이나 새 프리뷰 버전(예: `google/gemini-3.1-pro-preview`)으로 변경
404 `model_not_found`	`Model 'google/gemini-9-pro' not found`	모델 ID 철자가 틀림	이 페이지에서 모델 ID를 복사
401	—	`?key=`로 Key를 전달함	`x-goog-api-key` 요청 헤더를 사용
요청 타임아웃	—	사고가 기본적으로 켜져 있어 복잡한 질문은 시간이 오래 걸림	스트리밍 출력을 사용하고 클라이언트 타임아웃을 300초 이상으로 설정하거나 사고량을 줄임

기타 일반 오류는 오류 처리를 참고하십시오.

공식 문서

공식 문서는 Google에 직접 연결할 때의 동작을 설명합니다. OfoxAI에서 호출할 때는 모델 ID와 엔드포인트 주소를 이 페이지 기준으로 사용하십시오.

자주 묻는 질문

Gemini 모델 ID는 어떻게 작성합니까?

표준 표기법은 google/gemini-3.8-flash이며, google/ 접두사를 생략할 수도 있습니다. 네이티브 API 주소에서도 접두사를 붙이거나 생략할 수 있습니다.

Gemini 응답이 느리면 어떻게 합니까?

Flash-Lite를 제외한 Gemini는 기본적으로 사고가 켜져 있어 복잡한 질문은 1분 이상 걸릴 수 있습니다. thinkingLevel: "low"를 전달해 사고량을 줄이거나, 일부 모델에서는 thinkingBudget: 0으로 사고를 끄거나, 기본적으로 사고하지 않는 Flash-Lite 모델로 바꾸십시오.

Gemini에서 사고를 끄려면 어떻게 합니까?

3.5 Flash, 3 Flash Preview는 thinkingBudget: 0을 전달하면 사고를 끌 수 있습니다. 3.1 Pro Preview, 3.8 Flash는 완전히 끌 수 없으며 thinkingLevel: "low"로 사고량을 줄일 수 있습니다. Flash-Lite 시리즈는 기본적으로 사고하지 않습니다.

Gemini의 답변이 잘리고 finishReason이 MAX_TOKENS입니다.

사고 토큰도 maxOutputTokens에 포함됩니다. maxOutputTokens를 늘리거나 사고량을 줄이십시오.

Gemini로 웹 검색을 할 수 있습니까?

가능합니다. 네이티브 API에서는 tools에 {"google_search": {}}를 추가하면 응답의 groundingMetadata에 검색어와 출처가 포함됩니다. OpenAI 호환 API에서는 web_search_options: {}를 전달합니다.

Gemini 네이티브 API는 어떻게 인증합니까?

x-goog-api-key 요청 헤더로 OfoxAI API Key를 전달하며, Authorization: Bearer도 허용됩니다. URL 파라미터 ?key=는 지원하지 않습니다.

410 model_deprecated 오류가 납니다.

해당 프리뷰 모델이 서비스 종료된 것입니다. 예: gemini-3-pro-preview. google/gemini-3.1-pro-preview나 정식 버전 모델로 바꾸십시오.

Gemini로 오디오와 PDF를 분석할 수 있습니까?

가능합니다. 네이티브 API에서는 inline_data로 base64 인코딩된 파일을 전달합니다. OpenAI 호환 API에서는 PDF는 file 콘텐츠 블록, 오디오는 input_audio 콘텐츠 블록을 사용합니다.