Gemini 네이티브 형식 가이드

APIYI는 공식 Gemini 네이티브 형식(즉, /v1beta generateContent 엔드포인트)을 완전히 지원합니다. base_url을 https://api.apiyi.com로 지정하면 기존 Gemini 코드와 공식 SDK가 매끄럽게 이전되며, 형식 변환이 필요하지 않습니다. 이 페이지는 공식 Google 문서(ai.google.dev/gemini-api/docs, 2026년 6월 기준)를 바탕으로 작성되었습니다. 모든 예시는 복사해 바로 붙여넣을 수 있습니다.

네이티브 형식을 사용하는 이유

OpenAI 호환 형식으로도 Gemini를 호출할 수 있지만, 다음 기능은 네이티브 전용입니다:

완전한 추론 제어: thinking_level (Gemini 3 series) / thinking_budget (2.5 series), 사고 요약, 사고 서명
네이티브 멀티모달 Parts: 인라인 이미지 / 오디오 / 비디오, media_resolution 비용 제어 포함 — 멀티모달 및 코드 실행 참조
코드 실행 도구: code_execution가 샌드박스에서 Python을 실행합니다
세분화된 사용량 필드: thoughts_token_count, cached_content_token_count 등

일반 텍스트 채팅이나 여러 벤더에서 하나의 코드베이스를 사용할 때는 대신 OpenAI 호환 모드를 사용하십시오.

빠른 시작

Google의 공식 통합 SDK google-genai를 사용하십시오(기존 google-generative-ai는 2025년 11월 30일(UTC)에 종료되었습니다):

pip install google-genai

from google import genai

client = genai.Client(
    api_key="YOUR_API_KEY",  # your APIYI key
    http_options={"base_url": "https://api.apiyi.com"}
)

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Introduce yourself in one sentence"
)
print(response.text)

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({
  apiKey: 'YOUR_API_KEY',
  httpOptions: { baseUrl: 'https://api.apiyi.com' }
});

const response = await ai.models.generateContent({
  model: 'gemini-3.5-flash',
  contents: 'Introduce yourself in one sentence'
});
console.log(response.text);

curl "https://api.apiyi.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -d '{
    "contents": [{
      "parts": [{"text": "Introduce yourself in one sentence"}]
    }]
  }'

base_url은 https://api.apiyi.com (없이 /v1) — OpenAI 호환 형식의 https://api.apiyi.com/v1와는 다릅니다. APIYI 키를 사용하고, Google AI Studio 키는 사용하지 마십시오.

Streaming

stream = client.models.generate_content_stream(
    model="gemini-3.5-flash",
    contents="Write a short essay on quantum computing"
)

for chunk in stream:
    print(chunk.text, end="", flush=True)

추론 제어

Gemini 모델은 기본적으로 추론하며, 두 세대는 서로 다른 매개변수를 사용하므로 혼용하면 오류가 발생합니다:

모델 시리즈	매개변수	값
Gemini 3 / 3.1 / 3.5	`thinking_level`	`minimal` (Flash 패밀리만 해당) / `low` / `high` (기본값)
Gemini 2.5	`thinking_budget`	token 한도(예: 0–8192); 미설정 시 모델이 자동으로 제어합니다

Gemini 3 시리즈 모델에 thinking_level와 thinking_budget를 모두 전달하면 오류를 반환합니다 — 하나만 선택하십시오(3 시리즈에는 thinking_level를 사용하십시오).

from google.genai import types

# Gemini 3 series: level-based control
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Prove that the square root of 2 is irrational",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="high")
    )
)

# Gemini 2.5 series: token-budget control
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Simple question, be quick",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_budget=0)  # thinking off
    )
)

수준 선택: minimal은 지연 시간이 짧은 단순 작업(분류, 추출)에 적합합니다; low은 일반적인 채팅에 적합합니다; high은 복잡한 추론과 코드에 적합합니다. Thinking token은 출력 요율로 과금되므로, 수준이 높을수록 비용이 더 듭니다.

추론 요약 및 추론 서명

추론 요약: include_thoughts=True는 추론의 요약을 반환합니다(part.thought이 True인 부분)
추론 서명: Gemini 3에서 도입된 암호화된 추론 상태입니다. 멀티턴 대화(특히 function calling)에서는 응답의 thought_signature를 변경하지 않은 채 다시 전달해야 모델이 추론 체인을 계속할 수 있습니다. 공식 SDK는 이를 자동으로 처리합니다; 수동으로 작성한 REST 호출에서는 해당 필드를 제거하지 마십시오 — 함수 호출을 참조하십시오

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Analyze the time complexity of: def fib(n): return n if n <= 1 else fib(n-1) + fib(n-2)",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="high", include_thoughts=True)
    )
)

for part in response.candidates[0].content.parts:
    if getattr(part, "thought", False):
        print(f"[Thought summary] {part.text}")
    else:
        print(f"[Final answer] {part.text}")

공통 구성 매개변수

config (GenerateContentConfig)을 통해 전달됩니다:

매개변수	설명
`system_instruction`	시스템 prompt
`temperature`	0–2. Google은 Gemini 3 시리즈에서 기본값 1.0을 유지할 것을 권장합니다 — 이 값을 낮추면 추론 품질이 저하될 수 있습니다
`max_output_tokens`	출력 상한(생각 token 포함)
`thinking_config`	추론 제어, 위를 참조하십시오
`response_mime_type`	JSON 출력을 강제하려면 `application/json`을 설정하십시오
`response_schema`	구조화된 JSON 출력에 대한 스키마 제약
`tools`	함수 선언 / `code_execution` 및 기타 tools
`media_resolution`	멀티모달 입력 비용 제어, Multimodal 페이지를 참조하십시오

사용 항목 (usage_metadata)

usage = response.usage_metadata
print(f"Input: {usage.prompt_token_count}")
print(f"Output: {usage.candidates_token_count}")
print(f"Thinking: {usage.thoughts_token_count}")
print(f"Cache hits: {usage.cached_content_token_count}")

Field	Description	과금
`prompt_token_count`	Input tokens	입력 요율
`candidates_token_count`	Output tokens	출력 요율
`thoughts_token_count`	Thinking tokens	출력 요율 — 수준을 조정하여 절약
`cached_content_token_count`	Cached tokens	공식 할인, 캐시 과금 참조
`total_token_count`	Total	—

지원되는 모델 및 요금

모델	입력(1M tokens당)	출력(1M tokens당)	비고
`gemini-3.5-flash`	$1.50	$9.00	현재 주력 모델 — 여러 벤치마크에서 3.1 Pro를 앞서며, 1M 컨텍스트 윈도우
`gemini-3.1-pro-preview`	$1.80	$10.80	Pro 플래그십
`gemini-3-pro-preview`	$1.80	$10.80	이전 Pro
`gemini-3-flash-preview`	$0.44	$2.64	가볍고 빠름
`gemini-3.1-flash-lite`	$0.25	$1.50	초저가
`gemini-2.5-pro`	$1.25	$10.00	2.5 시리즈 Pro
`gemini-2.5-flash`	$0.30	$2.40	2.5 시리즈 주력 모델
`gemini-2.5-flash-lite`	$0.10	$0.40	가장 저렴함

일부 모델에는 -thinking / -nothinking 별칭 변형(예: gemini-3-flash-preview-nothinking)이 있으며, 이를 통해 thinking을 켜거나 끈 상태로 고정할 수 있습니다. 요청 매개변수를 바꿀 수 없는 클라이언트에 유용합니다. 전체 목록: Models & Pricing.

네이티브 vs OpenAI 호환

기능	Gemini 네이티브	OpenAI 호환
base_url	`https://api.apiyi.com`	`https://api.apiyi.com/v1`
SDK	`google-genai`	`openai`
추론 제어	`thinking_level` / `thinking_budget`	`reasoning_effort`
사고 요약 / 서명	✅	❌
코드 실행 도구	✅	❌
미디어 입력	네이티브 인라인 Parts (PIL / bytes)	Base64 image_url
캐시 적중 필드	`cached_content_token_count`	`cached_tokens`

참고

Files API는 지원되지 않습니다 (client.files.upload()); 미디어는 인라인으로 전달해야 하며 각 파일은 20MB 미만이어야 합니다 — Multimodal & Code Execution을 참조하십시오
캐시 할인과 캐시 적중률 기대치: 캐시 과금

기초

기본 API

이미지 API (공식)

동영상 API (공식)

멀티모달 이해 API

텍스트 API

Gemini 네이티브 형식 가이드

네이티브 형식을 사용하는 이유

빠른 시작

Streaming

추론 제어

추론 요약 및 추론 서명

공통 구성 매개변수

사용 항목 (usage_metadata)

지원되는 모델 및 요금

네이티브 vs OpenAI 호환

참고

관련 링크

​네이티브 형식을 사용하는 이유

​빠른 시작

​Streaming

​추론 제어

​추론 요약 및 추론 서명

​공통 구성 매개변수

​사용 항목 (usage_metadata)

​지원되는 모델 및 요금

​네이티브 vs OpenAI 호환

​참고

​관련 링크

네이티브 형식을 사용하는 이유

빠른 시작

Streaming

추론 제어

추론 요약 및 추론 서명

공통 구성 매개변수

사용 항목 (usage_metadata)

지원되는 모델 및 요금

네이티브 vs OpenAI 호환

참고

관련 링크