Gemini 3.6 Flash API 사용법

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 입력을 지원합니다. 이 가이드는 아무것도 모르는 상태에서 테스트된 요청을 만드는 과정을 안내합니다. 키를 얻고, curl과 Python으로 첫 호출을 만들고, 중요한 매개변수를 배우고, 배포 후에도 호출이 계속 작동하도록 회귀 테스트를 설정할 것입니다.

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

버튼

시작하기 전에 필요한 것

세 가지가 필요하며, 이 중 어느 것도 시작하는 데 비용이 들지 않습니다.

Google 계정. 키를 얻기 위해 로그인하는 데 사용됩니다.
Gemini API 키. Google AI Studio에서 무료로 제공되며, 다음 섹션에서 다룹니다.
HTTP 요청을 보낼 수 있는 방법. curl은 모든 터미널에서 작동합니다. 코드를 작성하고 싶다면 Python이 작동합니다. 전체적으로 UI를 원한다면 Apidog와 같은 API 클라이언트를 사용할 수도 있습니다. 세 가지 모두 보여드리겠습니다.

초기에 청구 설정은 필요하지 않습니다. 무료 등급은 AI Studio를 통해 실행되며 비율 제한이 있으므로, 카드 정보를 입력하지 않고도 테스트할 수 있습니다. 이러한 제한에 대한 자세한 내용은 아래에서 확인하세요.

Gemini API 키 받기

Google AI Studio로 이동하여 Google 계정으로 로그인합니다. "API 키 받기"를 클릭한 다음 "API 키 생성"을 클릭합니다. 받은 문자열을 복사하여 안전한 곳에 저장합니다. 비밀번호처럼 다루세요. 키를 가진 사람은 누구나 귀하의 계정을 사용할 수 있습니다.

클라이언트 측 코드에 키를 붙여넣지 마시고, 리포지토리에 커밋하지 마세요. 대신 환경 변수로 설정하세요:

export GEMINI_API_KEY="여기에_당신의_키"

공식 Python SDK는 이 변수를 자동으로 읽어 소스 파일에서 비밀이 노출되지 않도록 합니다. 정식 설정 단계는 Google의 Gemini API 문서를 참조하세요.

첫 API 호출하기

REST 엔드포인트는 모델의 generateContent 메서드에 대한 POST입니다. curl로 다음과 같습니다:

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

키는 x-goog-api-key 헤더에 들어갑니다. 본문은 contents 배열입니다. 각 항목에는 parts 배열이 있으며, 여기서는 각 부분이 text 문자열입니다. 이 중첩 구조는 단일 프롬프트에는 번거로워 보일 수 있지만, 나중에 하나의 요청에서 텍스트와 이미지 및 파일을 혼합할 수 있게 해주는 동일한 형태입니다.

Python을 선호하십니까? pip install google-genai로 SDK를 설치한 다음:

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)

클라이언트는 GEMINI_API_KEY를 자동으로 가져오므로, 코드에 키가 노출되지 않습니다. resp.text는 생성된 답변을 담고 있습니다. 5줄로 작동하는 호출입니다.

내부적으로 API는 JSON을 반환합니다. 생성된 텍스트는 candidates[0].content.parts[0].text에 있습니다. 이 가이드의 뒷부분에서 이 호출을 테스트로 전환할 때 이 필드를 정확히 단언할 것이므로 지금 알아두는 것이 좋습니다.

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

기본 요청은 작동하지만, 몇 가지 설정을 통해 얻는 결과가 달라집니다.

시스템 지시. 전체 대화에 적용되는 페르소나 또는 규칙 세트를 사용자 프롬프트와 분리하여 설정합니다. "JSON으로만 답변해라" 또는 "당신은 간결한 코드 검토자이다"와 같이 사용하세요. 이는 각 메시지에 지시를 넣는 것보다 훨씬 안정적으로 어조와 형식을 조절합니다.
최대 출력 토큰. 응답 길이를 제한합니다. 3.6 Flash는 최대 64k 출력 토큰을 생성할 수 있으므로, 긴 생성에는 상한선을 높이고 비용과 지연 시간을 제어하고 싶을 때는 낮추세요.
멀티모달 입력. 모델은 동일한 호출에서 텍스트, 이미지, 비디오, 오디오 및 PDF를 읽습니다. 텍스트와 함께 parts 배열에 추가 항목으로 추가합니다. 출력은 텍스트 전용이므로, 다양한 종류의 입력이 들어가서 단어로 나오는 것으로 생각하십시오. 컨텍스트 창은 최대 1M 입력 토큰을 수용하며, 이는 긴 PDF나 전체 비디오 전사본을 위한 충분한 공간입니다.
사고 및 추론. 3.6 Flash는 어려운 프롬프트에 답변하기 전에 추론합니다. 이는 다단계 작업을 개선하며, 출력 가격에 사고 토큰이 포함되는 이유입니다 (다음 섹션에서 더 자세히 설명). 속도와 깊이를 맞바꾸고 싶을 때 추론 노력을 조절할 수 있습니다.

전체 매개변수 목록은 Gemini API 문서에 있습니다. 필드 이름을 추측하지 마세요. 문서는 진실의 원천이며, 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은 호출이 한 번 작동함을 증명합니다. Google이 응답 필드를 변경할 때, 키가 만료될 때, 또는 배포가 조용히 요청을 손상시킬 때 curl은 알려주지 않습니다. 이를 위해서는 저장되고 반복 가능한 테스트가 필요합니다. 여기서 Apidog가 워크플로우에서 그 자리를 차지합니다.

Apidog는 API 클라이언트 및 테스트 플랫폼입니다. Gemini 호출에 대한 전체 흐름은 다음과 같습니다:

요청 생성. URL https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent로 새 POST 요청을 추가합니다. 이전에 사용한 JSON 본문을 요청 본문에 붙여넣습니다.
환경 변수에 키 저장. Apidog 환경에 GEMINI_API_KEY라는 변수를 추가한 다음, x-goog-api-key 헤더에서 {{GEMINI_API_KEY}}로 참조합니다. 비밀은 공유 요청 외부에 유지되며, 호출 자체를 건드리지 않고도 환경별로(개발, 스테이징, 프로덕션) 키를 교체할 수 있습니다.
단언 추가. 요청이 실행된 후 JSON 응답에 대해 단언합니다. 상태는 200이고, candidates[0].content.parts[0].text가 존재하며 비어 있지 않은지 확인합니다. 이제 통과된 실행은 API가 단순히 무언가를 반환한 것이 아니라 실제로 응답했다는 것을 의미합니다.
저장하고 스케줄링. 요청을 컬렉션에 저장하고 회귀 테스트로 스케줄링합니다. 타이머 또는 CI 내에서 실행하면, 사용자가 문제를 겪기 전에 Gemini 호출이 오작동하는 순간을 알 수 있습니다.

Apidog를 다운로드하면 몇 분 안에 이 테스트를 실행할 수 있습니다. 이것이 여기에 딱 맞는 이유입니다. Apidog는 모델을 실행하지 않지만, 귀하의 앱이 의존하는 API가 앱이 예상하는 방식으로 계속 응답하는지 확인합니다.

일반적인 오류 및 해결 방법

초기에 겪을 수 있는 대부분의 문제는 세 가지 오류로 요약됩니다.

401 Unauthorized (잘못된 키). 키가 잘못되었거나, 취소되었거나, 헤더에 없습니다. x-goog-api-key에 AI Studio의 정확한 문자열이 포함되어 있는지, 그리고 환경 변수가 실제로 해결되었는지 확인하십시오. 후행 공백이나 확장되지 않은 {{GEMINI_API_KEY}}가 일반적인 원인입니다.
429 Too Many Requests (요청 속도 제한). 무료 등급의 분당 또는 일일 상한선에 도달했습니다. 요청 속도를 늦추거나, 백오프와 함께 재시도를 추가하거나, 상한선을 높이려면 청구를 활성화하십시오. 짧은 테스트 루프는 이 문제를 빠르게 일으킵니다.
404 Not Found (모델을 찾을 수 없음). 이는 거의 항상 모델 ID의 오타입니다. 정확히 gemini-3.6-flash입니다. gemini-3.5-flash가 아니며, gemini-flash-3.6도 아닙니다. 동일한 릴리스의 Lite 등급은 gemini-3.5-flash-lite이며, 3.5 라인의 다른 모델이므로 혼동하지 마십시오.

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만 바꾸면 됩니다. 3.6 Flash는 출력 가격을 낮추고 동일한 작업에서 더 적은 출력 토큰을 사용합니다.

curl, Python, Apidog에서 동일한 키를 사용할 수 있나요? 예. AI Studio에서 받은 하나의 키는 모두에서 작동합니다. 하드코딩하는 대신 각 도구의 환경 변수에 보관하면, 한 곳에서 키를 교체하거나 취소할 수 있습니다.

여기서부터는 어디로 가야 할까요?

이제 키, curl과 Python에서 작동하는 호출, 중요한 매개변수, 그리고 엔드포인트를 감시하는 저장된 회귀 테스트를 갖게 되었습니다. 무료 등급으로 시작하고, 환경 변수에 키를 보관하며, 기본적인 것을 넘어선 모든 것에 대해서는 공식 문서에 의존하세요. 호출이 앱이 의존하는 중요한 부분이 되면, Apidog 테스트로 감싸서 조용한 API 변경이 사용자에게 먼저 도달하는 일이 없도록 하세요.

버튼