Gemini 3.6 Flash API 사용법

Gemini 3.6 Flash API 사용법

Gemini 3.6 Flash API 사용법Rihpig

Google Gemini API에서 모델 ID gemini-3.6-flash를 지정해 Gemini 3.6 Flash를 호출하는 방법을 정리합니다. Google은 2026년 7월...

Google Gemini API에서 모델 ID gemini-3.6-flash를 지정해 Gemini 3.6 Flash를 호출하는 방법을 정리합니다. Google은 2026년 7월 21일에 Flash를 새로 출시했으며, 3.6 Flash는 주력 등급 모델입니다. 3.5 Flash보다 낮은 출력 비용, 최대 1M 토큰 컨텍스트 창, 텍스트·이미지·비디오·오디오·PDF 입력을 지원합니다. 이 글에서는 API 키 발급부터 curl·Python 호출, 주요 매개변수 설정, 회귀 테스트 구성까지 단계별로 진행합니다.

지금 Apidog 사용해 보기

Gemini 3.6 Flash는 텍스트, 이미지, 비디오, 오디오 및 PDF를 처리할 수 있습니다.

시작하기 전에 필요한 것

다음 세 가지만 준비하면 됩니다.

  • Google 계정: API 키를 발급받기 위해 필요합니다.
  • Gemini API 키: Google AI Studio에서 발급합니다.
  • HTTP 클라이언트: 빠르게 확인하려면 curl, 애플리케이션에 통합하려면 Python, GUI에서 요청과 테스트를 관리하려면 Apidog를 사용할 수 있습니다.

초기 테스트에 청구 설정은 필요하지 않습니다. AI Studio 무료 등급에는 비율 제한이 있지만, 카드 정보를 등록하지 않고 API 호출을 검증할 수 있습니다.

Gemini API 키 받기

Google AI Studio에 접속해 Google 계정으로 로그인합니다.

  1. API 키 받기를 클릭합니다.
  2. API 키 생성을 클릭합니다.
  3. 생성된 키를 복사해 안전한 비밀 관리 위치에 저장합니다.

API 키를 얻기 위해 Google AI Studio에 로그인합니다.

API 키는 비밀번호처럼 다뤄야 합니다. 클라이언트 코드에 넣거나 Git 리포지토리에 커밋하지 마세요. 로컬 환경에서는 환경 변수로 설정합니다.

export GEMINI_API_KEY="여기에_당신의_키"
Enter fullscreen mode Exit fullscreen mode

공식 Python SDK는 GEMINI_API_KEY 환경 변수를 자동으로 읽습니다. 따라서 소스 파일에 키를 하드코딩할 필요가 없습니다. 최신 설정 방식은 Google Gemini API 문서를 확인하세요.

첫 API 호출하기

REST API에서는 generateContent 메서드로 POST 요청을 보냅니다.

curl로 호출하기

아래 예제에서 YOUR_API_KEY를 실제 키로 바꾸거나, 셸 환경 변수를 사용하세요.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "API 작동 방식 설명"
          }
        ]
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

요청 구조의 핵심은 다음과 같습니다.

  • x-goog-api-key: API 키를 전달하는 헤더
  • contents: 대화 또는 입력 콘텐츠 배열
  • parts: 하나의 콘텐츠에 포함할 텍스트·이미지·파일 등의 파트 배열
  • text: 텍스트 프롬프트

단일 텍스트 프롬프트에는 구조가 다소 길어 보일 수 있습니다. 하지만 같은 parts 배열에 이미지나 파일 입력을 추가할 수 있으므로, 멀티모달 요청으로 확장하기 쉽습니다.

응답 JSON에서 생성 텍스트는 일반적으로 다음 경로에 있습니다.

candidates[0].content.parts[0].text
Enter fullscreen mode Exit fullscreen mode

이 경로는 나중에 API 테스트에서 응답을 검증할 때도 사용합니다.

Python SDK로 호출하기

먼저 SDK를 설치합니다.

pip install google-genai
Enter fullscreen mode Exit fullscreen mode

그다음 GEMINI_API_KEY 환경 변수가 설정된 상태에서 아래 코드를 실행합니다.

from google import genai

client = genai.Client()  # GEMINI_API_KEY 환경 변수를 자동으로 읽습니다.

resp = client.models.generate_content(
    model="gemini-3.6-flash",
    contents="API 작동 방식 설명",
)

print(resp.text)
Enter fullscreen mode Exit fullscreen mode

resp.text에는 생성된 응답이 들어갑니다. 로컬에서 API 연결과 키 설정을 확인할 때 가장 간단한 방법입니다.

알아두면 좋은 주요 매개변수

기본 요청이 성공했다면, 다음 설정을 기준으로 호출을 확장하세요.

시스템 지시

시스템 지시는 사용자 프롬프트와 별도로 모델의 역할, 응답 형식, 규칙을 지정합니다.

예를 들면 다음과 같은 지시를 둘 수 있습니다.

  • JSON으로만 응답
  • 간결한 코드 리뷰어 역할 수행
  • 답변에 코드 예제를 반드시 포함
  • 한국어로만 응답

매 요청마다 같은 지시를 프롬프트에 반복하는 것보다 형식과 어조를 일관되게 유지하는 데 유용합니다.

최대 출력 토큰

최대 출력 토큰은 응답 길이를 제한합니다.

  • 긴 문서 생성, 상세 분석: 상한을 높게 설정
  • 짧은 분류, 요약, 자동완성: 상한을 낮게 설정
  • 비용과 지연 시간을 제한해야 하는 서비스: 명시적으로 제한

Gemini 3.6 Flash는 최대 64k 출력 토큰을 생성할 수 있습니다.

멀티모달 입력

Gemini 3.6 Flash는 하나의 호출에서 다음 입력을 처리할 수 있습니다.

  • 텍스트
  • 이미지
  • 비디오
  • 오디오
  • PDF

입력은 parts 배열에 추가합니다. 출력은 텍스트 전용입니다. 최대 1M 입력 토큰 컨텍스트 창을 지원하므로 긴 PDF, 대용량 전사본, 긴 문서 묶음을 처리하는 작업에 활용할 수 있습니다.

사고 및 추론

Gemini 3.6 Flash는 어려운 프롬프트에 답하기 전에 추론할 수 있습니다. 다단계 문제 해결에는 도움이 되지만, 사고 토큰도 출력 요금에 포함됩니다.

따라서 다음을 함께 조절해야 합니다.

  • 응답 품질
  • 지연 시간
  • 출력 토큰 사용량
  • 추론이 많은 작업의 비용

정확한 필드명과 최신 파라미터는 추측하지 말고 Gemini API 문서를 기준으로 구현하세요.

가격 및 무료 등급

Gemini 3.6 Flash 가격은 다음과 같습니다.

구분 가격
입력 1M 토큰당 $1.50
출력 1M 토큰당 $7.50

출력 요율은 3.5 Flash의 $9.00에서 인하되었습니다. 또한 3.6 Flash는 동일한 작업에서 약 17% 더 적은 출력 토큰을 생성하는 경향이 있어 비용 절감에 영향을 줄 수 있습니다.

주의할 점은 출력 비용에 사고 토큰이 포함된다는 것입니다. 화면에 보이는 답변이 짧아도 내부 추론이 많이 발생하면 출력 토큰 비용이 커질 수 있습니다. 비용을 예측해야 한다면 프롬프트 유형별 사용량을 측정하세요. 자세한 계산은 Gemini 3.6 Flash 가격 가이드를 참고하세요.

AI Studio 무료 등급도 사용할 수 있지만 분당 및 일일 요청 제한이 있습니다. 무료 등급 데이터는 Google의 제품 개선에 사용될 수 있으며, 프로덕션 트래픽보다는 학습과 프로토타이핑에 적합합니다.

무료로 시작하는 방법은 Gemini 3.6 Flash를 무료로 사용하는 방법에서 확인할 수 있습니다. 무료 등급 한도를 넘어서면 청구를 활성화할 수 있으며, 기존 키와 코드 구조를 그대로 유지할 수 있습니다.

Apidog에서 Gemini API 테스트 및 디버그

curl 호출 성공은 한 번의 연결 확인일 뿐입니다. 다음과 같은 문제가 생기면 반복 가능한 테스트가 필요합니다.

  • API 응답 필드 변경
  • API 키 만료 또는 교체
  • 배포 과정에서 헤더 또는 요청 본문 손상
  • 환경별 설정 차이
  • 비율 제한 또는 예기치 않은 오류 응답

이 경우 Apidog에서 요청을 저장하고 회귀 테스트로 관리할 수 있습니다.

1. POST 요청 만들기

새 요청을 만들고 다음 URL을 설정합니다.

POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent
Enter fullscreen mode Exit fullscreen mode

헤더를 추가합니다.

x-goog-api-key: {{GEMINI_API_KEY}}
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode

요청 본문에는 앞서 사용한 JSON을 넣습니다.

{
  "contents": [
    {
      "parts": [
        {
          "text": "API 작동 방식 설명"
        }
      ]
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

2. API 키를 환경 변수로 관리하기

Apidog 환경에 GEMINI_API_KEY 변수를 추가하고, 헤더에서는 다음처럼 참조합니다.

{{GEMINI_API_KEY}}
Enter fullscreen mode Exit fullscreen mode

이렇게 하면 요청 정의에 비밀 값을 저장하지 않고도 개발·스테이징·프로덕션 환경마다 다른 키를 적용할 수 있습니다.

3. 응답 단언 추가하기

최소한 다음 항목을 검증하세요.

  1. HTTP 상태 코드가 200인지
  2. candidates[0].content.parts[0].text가 존재하는지
  3. 생성된 텍스트가 비어 있지 않은지

이 검증이 있어야 단순히 HTTP 응답을 받은 것뿐 아니라, 모델이 실제 응답 콘텐츠를 생성했는지 확인할 수 있습니다.

4. 회귀 테스트로 스케줄링하기

요청을 컬렉션에 저장한 뒤 회귀 테스트로 스케줄링하세요.

  • 정해진 시간마다 실행
  • CI 파이프라인에서 실행
  • 배포 전후에 실행

Apidog를 다운로드하면 몇 분 안에 요청 저장과 테스트 구성을 시작할 수 있습니다. Apidog가 모델을 실행하는 것은 아니지만, 애플리케이션이 의존하는 Gemini API가 예상한 형식으로 계속 응답하는지 검증하는 데 사용할 수 있습니다.

일반적인 오류 및 해결 방법

401 Unauthorized: 잘못된 키

원인:

  • API 키가 잘못됨
  • 키가 취소됨
  • x-goog-api-key 헤더 누락
  • 환경 변수 값이 해석되지 않음
  • 키 앞뒤에 공백 포함

확인 순서:

  1. AI Studio에서 발급한 키와 실제 값이 일치하는지 확인합니다.
  2. 요청 헤더에 x-goog-api-key가 있는지 확인합니다.
  3. 셸에서는 echo $GEMINI_API_KEY로 환경 변수가 설정됐는지 확인합니다.
  4. API 클라이언트에서는 {{GEMINI_API_KEY}}가 실제 값으로 치환되는지 확인합니다.

429 Too Many Requests: 요청 속도 제한

원인:

  • 무료 등급의 분당 요청 한도 도달
  • 무료 등급의 일일 요청 한도 도달
  • 짧은 테스트 루프에서 과도하게 호출

해결 방법:

  • 요청 빈도를 낮춥니다.
  • 재시도 로직에 백오프를 추가합니다.
  • 필요한 경우 청구를 활성화해 한도를 높입니다.

404 Not Found: 모델을 찾을 수 없음

대부분 모델 ID 오타가 원인입니다.

정확한 모델 ID는 다음입니다.

gemini-3.6-flash
Enter fullscreen mode Exit fullscreen mode

다음 값과 혼동하지 마세요.

gemini-3.5-flash
gemini-flash-3.6
gemini-3.5-flash-lite
Enter fullscreen mode Exit fullscreen mode

특히 gemini-3.5-flash-lite는 3.5 라인의 Lite 모델입니다.

FAQ

Gemini 3.6 Flash의 정확한 모델 ID는 무엇인가요?

gemini-3.6-flash입니다. SDK의 모델 이름과 REST URL에서 :generateContent 앞 모델 경로에 사용합니다.

Gemini 3.6 Flash API는 무료로 사용할 수 있나요?

AI Studio를 통한 무료 등급이 있으며 속도 제한이 적용됩니다. 학습과 프로토타이핑에는 적합하지만, 프로덕션 트래픽에는 청구 활성화가 필요합니다. 자세한 내용은 무료로 사용하는 방법을 참고하세요.

모델에 무엇을 보낼 수 있나요?

텍스트, 이미지, 비디오, 오디오, PDF를 최대 1M 토큰 컨텍스트 창까지 보낼 수 있습니다. 출력은 텍스트 전용입니다.

청구서가 화면에 보이는 응답보다 높게 나온 이유는 무엇인가요?

1M 토큰당 $7.50의 출력 가격에는 모델의 사고 토큰이 포함됩니다. 추론이 많은 프롬프트는 표시된 답변 길이보다 더 많은 비용을 발생시킬 수 있습니다.

이전 Gemini 3.5 Flash API와 호출 방식이 같은가요?

호출 형태는 같습니다. 이미 Gemini 3.5 API를 사용했다면 모델 ID를 gemini-3.6-flash로 바꿔 시작할 수 있습니다. 3.6 Flash는 출력 가격을 낮추고 동일한 작업에서 더 적은 출력 토큰을 사용하는 경향이 있습니다.

curl, Python, Apidog에서 같은 키를 사용할 수 있나요?

예. AI Studio에서 발급한 하나의 키를 모두 사용할 수 있습니다. 단, 키를 하드코딩하지 말고 각 도구의 환경 변수 또는 비밀 관리 기능에 저장하세요.

다음 단계

이제 다음을 갖추었습니다.

  • Gemini API 키
  • curl에서 실행되는 기본 호출
  • Python SDK 호출
  • 주요 설정 항목
  • API 응답을 감시하는 회귀 테스트 구성 방식

무료 등급으로 먼저 연결을 검증하고, API 키는 항상 환경 변수로 관리하세요. 멀티모달 입력, 시스템 지시, 출력 토큰 제한처럼 기본 호출을 넘어서는 기능은 공식 Gemini API 문서를 기준으로 구현하는 것이 안전합니다.

Gemini 호출이 서비스의 핵심 경로가 되면 Apidog 테스트를 추가해 API 변경이나 배포 문제를 사용자보다 먼저 발견하세요.