DEV Community

Cover image for 제미니 3.8 플래시 API 활용 가이드: 상호작용 API, 사고 수준 및 Apidog에서 첫 호출
Rihpig
Rihpig

Posted on Originally published at apidog.com

제미니 3.8 플래시 API 활용 가이드: 상호작용 API, 사고 수준 및 Apidog에서 첫 호출

Gemini 3.8 Flash API 실전 가이드: Interactions, 레거시 API, 스트리밍과 비용 관리

구글은 2026년 9월 2일 Gemini 3.8 Flash를 출시했습니다. API 모델 ID는 미리보기 접미사 없이 gemini-3.8-flash이며, 2026년 12월 31일까지 초기 가격인 백만 입력 토큰당 $0.75, 백만 출력 토큰당 $3.75가 적용됩니다. 구글은 이 모델을 “더 열심히 작동하는” 모델로 설명합니다. 복잡한 작업에서 더 많은 추론 단계를 거치고 도구를 자주 호출하므로, 토큰 사용량과 비용이 증가할 수 있습니다.

오늘 Apidog를 사용해 보세요

이 가이드에서는 다음 내용을 단계별로 살펴봅니다.

  • AI Studio에서 API 키 발급
  • Interactions API를 사용한 첫 요청
  • 레거시 generateContent API 호출
  • 각 API에서 thinking_level을 설정하는 위치
  • 다중 턴 대화와 스트리밍
  • thoughtsTokenCount를 이용한 추론 비용 확인
  • 배포 전 Apidog에서 API 테스트 및 비용 회귀 방지

모델 개요와 벤치마크는 Gemini 3.8 Flash란 무엇인가를 먼저 확인하세요. 공식 설명은 구글의 출시 게시물에서 확인할 수 있습니다.

Gemini 3.8 Flash API 한눈에 보기

항목 값
모델 ID gemini-3.8-flash
기본 엔드포인트 POST /v1beta/interactions
레거시 엔드포인트 POST /v1beta/models/gemini-3.8-flash:generateContent
인증 헤더 x-goog-api-key
컨텍스트 / 출력 1,048,576 입력 토큰 / 65,536 출력 토큰
입력 텍스트, 이미지, 비디오, 오디오, PDF (텍스트 출력만 해당)
추론 수준 low, medium (기본), high; minimal은 오류 반환
가격 (2026년 12월 31일까지 초기) 1백만 토큰당 $0.75 / $3.75; 2027년 1월 1일부터 $1.50 / $7.50

기본 추론 수준은 Gemini 3 Pro와 달리 high가 아니라 medium입니다. 추론 토큰은 공식 가격 책정 페이지의 출력 요율로 청구되므로, 추론 수준은 품질뿐 아니라 비용에도 영향을 줍니다. 작업별 비용은 Gemini 3.8 Flash 가격 분석에서 확인할 수 있습니다.

1단계: AI Studio에서 API 키 얻기

Google AI Studio에 로그인한 뒤 키 페이지에서 API 키를 생성합니다.

무료 등급에서도 즉시 사용할 수 있지만 속도 제한이 있으며, Google은 무료 등급 데이터가 “제품 개선에 사용된다”고 명시합니다. 프로덕션 환경에서 더 높은 한도를 사용하려면 결제 계정을 연결해 Tier 1로 이동하세요.

키를 코드에 직접 입력하지 말고 환경 변수로 내보냅니다.

export GEMINI_API_KEY="AIza..."
Enter fullscreen mode Exit fullscreen mode

공식 Python SDK는 GEMINI_API_KEY를 환경에서 읽으므로 genai.Client()에 키를 전달하지 않아도 됩니다.

pip install google-genai
Enter fullscreen mode Exit fullscreen mode

2단계: Interactions API로 첫 요청 보내기

구글은 Interactions API를 Gemini 3.x 모델의 기본 호출 방식으로 취급합니다. 요청에는 모델, input, 선택적인 generation_config가 포함됩니다.

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-[REDACTED CREDENTIAL] \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Explain HTTP caching in 3 sentences.",
    "generation_config": {"thinking_level": "medium"}
  }'
Enter fullscreen mode Exit fullscreen mode

응답은 단일 메시지가 아니라 실행 단계 목록입니다. 추론과 도구 호출이 각각 단계로 표시되고, 최종 텍스트는 model_output 단계에 포함됩니다.

Python SDK에서는 최종 텍스트를 간단히 읽을 수 있습니다.

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain HTTP caching in 3 sentences.",
    generation_config={"thinking_level": "medium"},
)

print(interaction.output_text)
Enter fullscreen mode Exit fullscreen mode

temperature, top_p, top_k는 설정하지 않는 것이 좋습니다. 구글은 Gemini 3 모델에서 temperature를 기본값인 1.0으로 유지할 것을 권장합니다. 값을 낮추면 “루프 또는 성능 저하를 유발할 수 있기” 때문입니다. 기존 모델의 설정을 복사했다면 해당 옵션부터 제거하세요.

3단계: previous_interaction_id로 다중 턴 대화 구현하기

Interactions API는 기본적으로 서버에 대화 상태를 저장합니다. 이전 응답의 id를 previous_interaction_id로 전달하면 전체 대화 기록을 다시 보낼 필요가 없습니다.

follow_up = client.interactions.create(
    model="gemini-3.8-flash",
    input="Now give one example of a Cache-Control header.",
    previous_interaction_id=interaction.id,
)
print(follow_up.output_text)
Enter fullscreen mode Exit fullscreen mode

서버 측 저장이 허용되지 않는 환경에서는 store: false를 사용하세요. 이 경우 상태를 직접 관리해야 하며, 모델의 추론 블록과 추론 서명을 매 턴 받은 그대로 다시 전달해야 합니다. 도구 사용 시에도 같은 규칙이 적용됩니다. 자세한 내용은 Gemini 3.8 Flash 함수 호출 가이드를 참고하세요.

4단계: 레거시 generateContent 경로 사용하기

프로덕션 환경의 많은 Gemini 코드는 여전히 generateContent를 사용합니다. Google은 이 API를 레거시로 분류하지만, 서비스 종료일 없이 “완전히 지원”하고 있으므로 즉시 마이그레이션할 필요는 없습니다.

Gemini 3.7 Flash API 가이드에서 다룬 방식과 거의 동일합니다. 다만 추론 설정 위치와 필드 이름이 Interactions API와 다릅니다.

cURL

generateContent에서는 thinkingLevel이 generationConfig.thinkingConfig 아래에 위치하며 카멜케이스를 사용합니다.

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-[REDACTED CREDENTIAL]" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Explain HTTP caching in 3 sentences."}]}],
    "generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}
  }'
Enter fullscreen mode Exit fullscreen mode

Python 

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Explain HTTP caching in 3 sentences.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="low")
    ),
)
print(response.text)
Enter fullscreen mode Exit fullscreen mode

thinking_budget을 정수로 사용하던 코드라면 문자열 열거형으로 변경하세요. candidate_count도 Gemini 3 이상에서는 제거되었습니다. 변경 전후 JSON을 포함한 전체 체크리스트는 3.7에서 3.8 Flash 마이그레이션 가이드에서 확인할 수 있습니다.

두 API의 주요 차이

관심사 Interactions API 레거시 generateContent
추론 수준 generation_config.thinking_level generationConfig.thinkingConfig.thinkingLevel
대화 상태 previous_interaction_id (서버 측) 전체 contents 배열 재전송
도구 결과 call_id + name을 포함한 function_result id + name을 포함한 functionResponse
최종 텍스트 model_output 단계 (SDK에서는 output_text) candidates[0].content.parts[].text
추론 서명 store: false가 아니면 자동 처리 받은 모든 부분을 정확히 재전달

5단계: 스트리밍과 추론 비용 확인하기

채팅 UI에서는 엔드포인트 이름을 streamGenerateContent로 바꾸고 ?alt=sse를 추가하면 서버 전송 이벤트를 받을 수 있습니다.

curl -N "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-[REDACTED CREDENTIAL] \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"List three HTTP caching headers."}]}]}'
Enter fullscreen mode Exit fullscreen mode

스트리밍 여부와 관계없이 generateContent 응답에는 usageMetadata가 포함됩니다. 모든 호출에서 다음 값을 기록하세요.

"usageMetadata": {
  "promptTokenCount": 12,
  "candidatesTokenCount": 84,
  "thoughtsTokenCount": 310,
  "totalTokenCount": 406
}
Enter fullscreen mode Exit fullscreen mode

특히 thoughtsTokenCount를 확인해야 합니다. 추론 토큰은 초기 기간 동안 백만 토큰당 $3.75의 출력 토큰 요율로 청구됩니다. Google은 모델이 “특히 높은 노력 수준에서 성능을 극대화하기 위해 더 많은 토큰을 사용할 수 있다”고 설명합니다.

Artificial Analysis 측정 결과는 다음과 같습니다.

  • high: 작업당 약 48,000 출력 토큰, 비용 약 $0.58
  • medium: 작업당 약 $0.41
  • low: 작업당 약 $0.24

high 수준의 작업당 비용은 3.7 Flash보다 약 30% 증가했으며, 토큰당 가격은 동일합니다. Gemini 3.8 Flash 추론 수준 가이드는 이러한 수치를 API 경로별 전략으로 정리합니다.

모델의 추론 요약을 확인하려면 thinkingConfig에 다음 옵션을 추가하세요.

"includeThoughts": true
Enter fullscreen mode Exit fullscreen mode

그러면 "thought": true 플래그가 지정된 부분으로 추론 요약이 반환됩니다. 최종 사용자에게 답변을 보여줄 때는 해당 부분을 제외하세요.

첫 시간에 자주 만나는 오류

thinking_level: "minimal" 유효성 검사 실패

Gemini 3.8 Flash가 지원하는 수준은 low, medium, high입니다. minimal을 보내면 다음과 함께 400 INVALID_ARGUMENT가 반환됩니다.

Thinking level MINIMAL is not supported for this model.
Please retry with other thinking level.
Enter fullscreen mode Exit fullscreen mode

해결 방법은 minimal을 low로 변경하는 것입니다. 이전 3.x 설정이나 오래된 코드 조각을 복사할 때 자주 발생합니다.

429 오류

429는 일반적으로 버그가 아니라 등급 제한에 도달했다는 의미입니다. 속도 제한 페이지에서 등급별 조건을 확인하세요.

  • 무료 등급: 속도 제한 적용
  • Tier 1: 결제 계정 연결
  • Tier 2: $100 지출 및 3일 경과
  • Tier 3: $1,000 지출 및 30일 경과

모델별 분당 요청 수와 분당 토큰 수는 AI Studio의 속도 제한 페이지에서 확인하는 것이 가장 정확합니다. 429가 발생하면 잠시 기다렸다가 재시도하고, 낮은 볼륨에서도 반복되면 등급 업그레이드를 고려하세요.

오프라인 작업에는 Batch API가 적합합니다. 초기 기간 동안 50% 할인된 가격이 적용됩니다.

  • 입력: 백만 토큰당 $0.375
  • 출력: 백만 토큰당 $1.875
  • 대기열 토큰 제한: Tier 1 3M, Tier 2 400M, Tier 3 1B

요청 형식은 Gemini Batch 모드 가이드에서 확인할 수 있습니다.

함수 결과에 call_id 누락

도구를 사용하는 경우 다음 필드를 모두 전달해야 합니다.

  • Interactions API의 function_result: call_id, name
  • 레거시 API의 functionResponse: 일치하는 id, name

하나라도 빠지면 해당 턴이 실패합니다.

배포 전에 Apidog에서 두 엔드포인트 테스트하기

터미널에서 두 요청이 작동하면 Apidog를 다운로드해 프로젝트를 만들고, 두 엔드포인트를 저장된 요청으로 추가하세요.

1. API 키를 환경 변수로 분리하기

환경 변수에 GEMINI_API_KEY를 추가한 뒤 헤더에서 다음처럼 참조합니다.

x-goog-[REDACTED CREDENTIAL]GEMINI_API_KEY}}
Enter fullscreen mode Exit fullscreen mode

저장된 요청에 비밀 키를 포함하지 않으면 무료 키와 유료 키를 환경 변경만으로 전환할 수 있습니다.

2. 상태와 토큰 사용량에 어설션 추가하기

HTTP 상태가 200인지 확인하고, 다음 JSON 경로에 어설션을 추가하세요.

usageMetadata.thoughtsTokenCount
Enter fullscreen mode Exit fullscreen mode

프롬프트별 상한선을 정해 두면 비용 회귀를 감지할 수 있습니다. 프롬프트 변경이나 자동 모델 변경으로 추론 토큰이 증가하면 청구서가 발생하기 전에 테스트가 실패합니다.

스트리밍 변형은 SSE 테스트 가이드에서 확인할 수 있습니다. Apidog는 SSE를 원시 청크가 아닌 병합된 이벤트 스트림으로 렌더링합니다.

3. 세 가지 추론 수준 비교하기

동일한 프롬프트를 low, medium, high로 각각 실행하고 다음 항목을 비교하세요.

  • thoughtsTokenCount
  • 응답 시간
  • 최종 응답 품질

인덱스 평균이 아닌 실제 프롬프트 기준의 비용과 성능을 확인할 수 있습니다.

4. API 테스트 예약하기

요청을 테스트 시나리오로 전환하고 일정에 따라 실행하세요. 다음과 같은 변화가 프로덕션 장애나 청구서가 아니라 테스트 보고서에서 먼저 나타납니다.

  • 속도 제한 변경
  • minimal 제거와 같은 유효성 검사 변경
  • 추론 토큰 급증

설정 방법은 Apidog에서 API 테스트를 예약하는 방법에서 확인할 수 있습니다.

Apidog는 모델 실행기나 SDK 대체재가 아닙니다. 대신 HTTP 호출을 저장하고, 공유하고, 어설션할 수 있는 형태로 관리해 배포 전 문제를 발견하도록 돕습니다.

FAQ

새 프로젝트에는 어떤 엔드포인트를 사용해야 하나요?

Interactions API를 사용하세요. Google은 generateContent를 레거시로 분류하지만 여전히 완전히 지원합니다. 새로운 기능은 Interactions API에 먼저 출시되며, 서버 측 상태 덕분에 다중 턴 코드도 짧아집니다.

기존 서비스는 마이그레이션할 이유가 생길 때까지 generateContent를 계속 사용해도 됩니다.

Gemini 3.8 Flash를 호출하려면 유료 계정이 필요한가요?

아니요. 무료 AI Studio 키로도 호출할 수 있습니다. 다만 속도 제한과 Google의 데이터 사용 약관이 적용됩니다.

Gemini 3.8 Flash 무료 사용 가이드에서 무료 등급의 제한을 확인할 수 있습니다. Gemini 앱에서 3.8 Flash를 사용하려면 AI Pro 또는 Ultra 플랜이 필요하다는 점도 참고하세요.

3.8 Flash가 3.7 Flash보다 느린가요?

토큰당 속도는 크게 다르지 않습니다8 Flash가 2.5분이었습니다.

계속 Gemini 3.7 Flash를 호출할 수 있나요?

예. Google은 3.7 Flash가 “완전히 지원된다”고 밝혔으며 서비스 중단일을 발표하지 않았습니다. 3.8 Flash의 추가 토큰 지출이 워크로드에 이득이 없다면 현재 버전을 유지해도 됩니다.

3.8 Flash는 Live API 또는 이미지 생성을 지원하나요?

아니요. 텍스트만 출력합니다. 오디오 생성, 이미지 생성, Live API는 지원하지 않습니다.

다음 단계

이제 다음을 구현할 수 있습니다.

  • Interactions API와 generateContent를 통한 두 가지 호출 경로
  • previous_interaction_id를 이용한 다중 턴 대화
  • 스트리밍 응답
  • thoughtsTokenCount 기반 비용 모니터링
  • 추론 수준별 성능 비교 및 회귀 테스트

다음으로 Gemini 3.8 Flash 함수 호출 가이드를 통해 도구를 연결하고, 추론 수준 가이드를 바탕으로 작업별 수준을 선택하세요.

마이그레이션을 검토 중이라면 3.8 Flash와 3.7 Flash 비교에서 장단점을 확인하고, 비용 변동이 테스트 실패로 나타나도록 Apidog 시나리오를 계속 실행하세요.

Top comments (0)