Gemini 3.1 pro API 사용 방법

Gemini 3.1 Pro에 대한 실용적이고 코드 중심의 가이드 — 모델 개요, 호출 방법(CometAPI 포함), 멀티모달 및 “thinking level” 제어, 함수 호출/도구 사용, 바이브 코딩 팁, 그리고 GitHub Copilot, VS Code, Gemini CLI, Google Antigravity와의 통합. Gemini 3.1 Pro는 개발자 중심의 스토리를 앞세워 대규모 멀티모달 모델의 경계를 넓히고 있습니다: 더 큰 컨텍스트 윈도우, 구성 가능한 “thinking” 모드, 향상된 도구·함수 호출, 그리고 에이전트형 워크플로우에 대한 명시적 지원.

Gemini 3.1 Pro란?

Gemini 3.1 Pro는 Gemini 3 제품군의 최신 “Pro” 티어로, 멀티모달을 네이티브로 지원하고 복잡한 다단계 작업과 에이전트형 도구 사용에 최적화된 reasoning-first 모델입니다. 이는 Gemini 3 Pro의 정제판으로 제시되며, 세 가지 실용적 초점에 맞춰 튜닝되었습니다: 더 강한 추론/사실 근거, 더 나은 토큰 효율, 그리고 개발자 워크플로우(코드, 기획, RAG 작업)를 겨냥한 제어 가능한 실행 모드. 모델 카드와 개발자 페이지는 이 모델이 소프트웨어 엔지니어링 동작, 에이전트 파이프라인, 그리고 멀티모달 입력(텍스트, 이미지, 오디오, 비디오, 리포지토리)에 최적화되어 있다고 설명합니다.

왜 중요한가: 백만 토큰급 컨텍스트 윈도우(여러 공급자 변형에서 제공), 명시적 함수 호출 프리미티브, 그리고 “thinking level” 제어의 조합은, 빠른 프로토타이핑부터 프로덕션 에이전트 오케스트레이션까지 팀이 비용과 출력을 보다 예측 가능하게 다루도록 돕습니다. CometAPI는 이미 API 마켓플레이스와 OpenAI 호환 브리지를 통해 3.1 Pro를 서피싱하고 있으며, 종량제 접근 방식을 제공합니다.

Gemini 3.1 Pro API는 어떻게 사용할 수 있나요(CometAPI)?

시작 전에 무엇이 필요하나요?

체크리스트(사전 준비물)

CometAPI 계정과 CometAPI API 키(환경 변수에 보관).
선택 사항: Google Cloud / Google AI Studio 프로젝트 및 Gemini API 키(Comet을 통해 호출하는 경우 필수 아님).
python 3.9+ 또는 node 18+, 빠른 테스트용 curl.
안전한 비밀 관리 메커니즘: 환경 변수, 볼트, 또는 CI 시크릿 스토어.
Comet 콘솔에서 Gemini 3.1 Pro의 Comet 모델 ID 확인(예: "google/gemini-3.1-pro" 또는 Comet 전용 별칭).

CometAPI는 Gemini 네이티브 포맷 호출과 OpenAI의 채팅 포맷 호출을 모두 지원합니다. CometAPI는 단일 베이스 URL과 SDK를 제공하여 모델 전환을 단순화하고, 멀티 벤더 스택의 통합 마찰을 줄여줍니다.

아래는 두 가지 구체적인 복사-붙여넣기용 예제입니다. 첫 번째는 CometAPI(OpenAI 호환 클라이언트)를 통해 Gemini를 호출하는 방법이고, 두 번째는 Google의 공식 Gemini HTTP 엔드포인트를 통해 호출하는 방법입니다. 공급자 키로 YOUR_API_KEY를 바꾸고, 노출된 공급자 사용 가능 변형명(예: gemini-3.1-pro-preview)으로 모델 이름을 설정하세요.

예시: CometAPI를 사용해 Gemini 3.1 Pro 호출(curl + Python)

Curl(CometAPI 베이스 URL을 사용하는 OpenAI 호환 래퍼)

# curl example: CometAPI (OpenAI-compatible)curl https://api.cometapi.com/v1/chat/completions \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "gemini-3.1-pro-preview",    "messages": [      {"role":"system","content":"You are a concise programming assistant."},      {"role":"user","content":"Write a Python function to fetch CSV from a URL and return pandas DataFrame."}    ],    "max_tokens": 800  }'

Python(CometAPI base_url로 설정된 OpenAI 호환 클라이언트)

from openai import OpenAI  # or openai-python-compatible SDK offered by your platformclient = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.cometapi.com/v1")resp = client.chat.completions.create(    model="gemini-3.1-pro-preview",    messages=[        {"role": "system", "content": "You are a concise programming assistant."},        {"role": "user", "content": "Write a Python function to fetch CSV from a URL and return pandas DataFrame."}    ],    max_tokens=800,)print(resp.choices[0].message.content)

이유: CometAPI는 많은 문서에서 OpenAI 호환 브리지를 제공하므로, base_url과 모델 이름만 바꾸면 기존 OpenAI 클라이언트 코드를 재사용할 수 있습니다. 이는 멀티 공급자 실험과 빠른 프로토타이핑에 유용합니다.

예시: 공식 Gemini API를 통한 호출(Node.js / HTTP)

Google의 공식 Gemini 엔드포인트는 전체 기능 세트(thinking-level 제어, 함수 호출, 멀티모달 업로드)에 가장 적합합니다. 아래는 Google AI 개발자 문서에 설명된 Gemini API 서피스를 사용하는 최소한의 HTTP 예시입니다.

공식 SDK 또는 요청의 Base URL과 API Key를 다음과 같이 교체해 사용하세요:

Base URL: https://api.cometapi.com(generativelanguage.googleapis.com를 교체)
API Key: $GEMINI_API_KEY를 $COMETAPI_KEY로 교체

Curl(공식 Gemini API — 예시용)

curl "https://api.cometapi.com/v1beta/models/gemini-3-1-pro-preview:generateContent" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "How does AI work?"
          }
        ]
      }
    ]
  }'

자주 설정하는 매개변수

temperature(0.0–1.0) — 무작위성. 결정적인 코드 출력을 원하면 0.0 사용.
max_output_tokens / max_tokens — 출력 길이 예산.
top_p — 누클리어스 샘플링.
presence_penalty / frequency_penalty — 반복 억제.
thinking_level 또는 모델 변형 — 추론 심도 결정(예: -low, -medium, -high 또는 명시적 thinking_level). 정확도 요구를 충족하는 가장 낮은 레벨을 사용해 비용/지연을 제어하세요.

Gemini 3.1 Pro의 멀티모달 기능은?

Gemini 3.1 Pro가 지원하는 모달리티는?

Gemini 3.1 Pro는 여러 프리뷰 빌드에서 텍스트, 이미지, 비디오, 오디오, PDF를 수용하며, 멀티모달 콘텐츠를 참조하거나 요약하는 텍스트 출력을 생성할 수 있습니다. Comet은 이미지 URL, 파일 업로드(Comet file API), 또는 클라우드 스토리지에 저장된 파일을 Gemini가 읽게 하는 방식으로 멀티모달 입력 전달을 지원합니다.

개발자는 멀티모달 프롬프트를 어떻게 구성해야 하나요?

명확한 컨텍스트 블록으로 프롬프트를 구조화하세요: 짧은 텍스트 지시를 먼저 두고, 이미지/비디오/PDF에 대한 메타데이터나 포인터를 첨부합니다.
바이너리를 텍스트 필드에 직접 넣기보다 SDK의 미디어 첨부 및 파일 업로드 필드를 사용하세요 — 공식 클라이언트와 Vertex AI / Gemini API 예제는 미디어 첨부를 깔끔하게 전달하는 방법을 보여줍니다.

실용 예시(의사코드): 이미지 + 질문 제시

# Pseudocode — attach an image with a caption and ask a questionfrom google.gemini import GemSDK  # conceptual import; use official client per docsresponse = client.generate(    model="gemini-3.1-pro-preview",    inputs = [        {"type": "text", "content": "Summarize the visual diagram and list actionable next steps."},        {"type": "image", "uri": "gs://my-bucket/diagram.png", "alt": "system architecture diagram"}    ])print(response.text)

실용 팁:

UI 버그 트리아지에 이미지 첨부를 활용하세요: 스크린샷을 붙이고 차이점 또는 가능한 원인을 요청합니다.
오디오 전사와 코드 샘플을 결합해 인터뷰 녹음 요약에 사용하세요.
큰 아티팩트(비디오, 대형 코드베이스)를 보낼 때는 단계적 접근을 선호하세요: 자산을 업로드(클라우드 스토리지), URL + 짧은 매니페스트를 전달하고, 모든 것을 한 번에 프롬프트에 넣기보다 모델이 RAG 파이프라인을 주도하게 하세요.

Thinking Levels(Low, Medium, High)이란 무엇이며, 언제 사용하나요?

“thinking levels”란?

Gemini 3 시리즈는 모델의 내부 연산/사고 사슬 예산을 안내하는 thinking_level 매개변수를 도입했습니다. 이는 지연 + 비용과 추론 심도 사이의 균형을 조절하는 노브로 생각하면 됩니다:

Low: 최소한의 추론, 처리량과 짧은 결정적 작업에 최적화.
Medium: 균형 잡힌 추론 — 3.1의 신규 기본값으로 많은 엔지니어링/분석 워크플로우에 적합.
High: 더 깊은 추론, 동적 체인-오브-소트 스타일; 복잡한 다단계 문제에 최적.
(다른 변형에서는 minimal/max 명명법이 있습니다 — 변형별 이용 가능 옵션은 모델 문서를 확인하세요.)

thinking level은 어떻게 선택하나요?

Low: 처리량이 중요한 사용자 채팅, 짧은 지시, 비용/지연이 핵심일 때.
Medium: 적정 수준의 추론이 필요한 대부분의 개발자 작업의 기본값.
High: 퍼즐 풀이, 긴 논리 사슬, 기획, 높은 정밀도가 필요하고 더 큰 지연/토큰 소모를 감수할 때.

요청에서 thinking level 설정 방법

curl "https://api.cometapi.com/v1beta/models/gemini-3-1-pro-preview:generateContent" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{ "parts": [{ "text": "Explain quantum physics simply." }] }],
    "generationConfig": {
      "thinkingConfig": {
        "thinkingLevel": "LOW"
      }
    }
  }'

Gemini 3.1 Pro로 함수 호출과 도구 사용을 어떻게 구현하나요?

함수 호출/도구 사용이란?

함수 호출(도구 사용이라고도 함)은 모델이 어떤 외부 도구나 함수를(예: get_current_weather(location)) 어떤 인자로 실행해야 하는지를 알려주는 구조화된 “call” 객체를 내보내게 합니다. 모델은 여러 호출을 연쇄하고, 도구 출력을 받아 계속 추론할 수 있어 에이전트형 동작을 가능하게 합니다. Gemini SDK는 모델↔도구 루프(MCP/tool registry)에 대한 내장 지원을 제공하여 안전한 자동 실행을 돕습니다.

구성을 통해 프록시 동작을 활성화하려면 도구를 선언할 수 있습니다. 내장 지원 도구로는 google_search, code_execution, url_context 커스텀 함수 등이 포함됩니다.

안전한 도구 사용 패턴

도구 인터페이스 선언: 명확한 스키마와 검증된 인자 타입으로 함수/도구를 등록합니다.
모델에 호출 제안을 맡김: 모델이 어떤 도구를 호출할지 JSON으로 구조화해 내보냅니다.
호스트가 허용된 도구만 실행: 허용 목록과 엄격한 검증을 강제합니다.
도구 출력을 모델에 반환: SDK 루프가 도구 응답을 모델에 다시 공급하여, 모델이 계속 계획/추론/추가 실행을 할 수 있도록 합니다.

Gemini 3.1 Pro 통합 가이드

GitHub Copilot

GitHub Copilot(Copilot)은 프리미엄 티어에서 Gemini 계열 모델을 지원하도록 확장되어, 팀이 Copilot의 챗 및 제안의 기반 모델로 Gemini를 선택할 수 있습니다. 즉, 적격 플랜 사용자는 Copilot 모델 피커에서 Gemini 변형을 선택해, IDE 확장을 바꾸지 않고도 모델 수준의 개선을 누릴 수 있습니다. 팀 단위로는 Copilot이 VS Code 등 지원 에디터 안에서 Gemini 추론을 사용하는 편리한 관리 경로로 남습니다.

Gemini CLI와 Code Assist

오픈소스 Gemini CLI는 터미널에서 Gemini 모델을 노출하며, 가볍고 기존 워크플로우(diff, 커밋, CI, 헤드리스 서버 실행)와 통합됩니다. CLI는 빠른 반복, 에이전트 실행 스크립팅, 또는 DevOps 흐름에 모델을 내장하기에 적합합니다. Gemini Code Assist는 VS Code 확장 및 더 넓은 IDE 통합으로, 컨텍스트 인식 코드 제안, PR 리뷰, 자동 수정을 에디터에 직접 제공합니다. 이 도구들은 모델 선택, 컨텍스트 윈도우, thinking level 기본값을 제어할 수 있게 합니다.

Visual Studio Code

Visual Studio Code와 마켓플레이스에는 GitHub Copilot과 Gemini Code Assist가 모두 제공됩니다. Gemini용 Code Assist를 설치하거나 Copilot을 계속 사용할 수 있으며, 각각 속도, 심도, 프라이버시 면에서 상이한 트레이드오프가 있습니다. VS Code는 대화형 코드 생성, 에디터 내 채팅, 로컬 실행/테스트 하네스와의 직접 통합에 가장 성숙한 서피스입니다.

Google Antigravity

Google Antigravity는 에이전트 우선 IDE이자 플랫폼으로, 에이전트를 일급 객체로 취급하며 에이전트 오케스트레이션을 위한 “Mission Control”, 내장 브라우저 자동화, 멀티 에이전트 프로젝트용 UI를 제공합니다. Antigravity와 Gemini CLI는 서로 다른 니즈를 충족합니다: Antigravity는 완전한 에이전트형 IDE 서피스이며, Gemini CLI는 터미널 네이티브이지만 확장과 MCP(Model Context Protocol) 서버를 통해 Antigravity 및 VS Code와 통합됩니다. Antigravity 생태계는 강한 에이전트 오케스트레이션과 더 의견이 분명한 시각적 서피스를 원하는 팀에 적합합니다.

누가 무엇을 써야 하나요?

빠른 프로토타이핑 & 단일 파일 편집: 속도를 위해 Gemini CLI + 로컬 테스트 또는 Copilot.
깊은 추론, 장시간 리서치: 고 thinking level과 함수 호출을 사용하는 Gemini API(Vertex).
에이전트 오케스트레이션 & 다단계 자동화: 시각적 관리용 Antigravity 또는 함수 호출 + MCP를 사용하는 커스텀 에이전트 파이프라인.
멀티 벤더 실험/비용 통제: CometAPI 같은 게이트웨이를 사용해 Flash와 Pro를 경제적으로 전환.

통합 시 설계 고려사항:

보안: 시크릿이나 PII를 프롬프트에 보내지 마세요. 서버사이드 호출에는 토큰 범위가 제한된 서비스 계정을 사용하세요.
로컬 vs 클라우드: 가벼운 어시스턴트 기능(빠른 완성)은 로컬에서, 대형 멀티모달 분석은 클라우드로 라우팅하세요.
사용자 제어: 모델이 생성한 코드 편집에 대해 “설명 보기”와 손쉬운 롤백을 제공합니다.

통합 패턴 & 권장 아키텍처

경량 앱(챗 또는 어시스턴트)

Client(브라우저/모바일) → 백엔드 마이크로서비스 → Gemini API(thinking_level=low)
채팅 UX를 위해 스트리밍/부분 출력 사용. 사용자 입력을 검증하고, 신뢰할 수 없는 클라이언트에서의 원시 도구 호출을 절대 허용하지 마세요.

에이전트형 백엔드(자동화 워크플로우)

오케스트레이터 서비스: 화이트리스트된 소수의 도구(DB 읽기, CI 잡 실행기, 내부 API)를 등록.
Gemini에 계획과 도구 호출 생성을 맡기고, 오케스트레이터가 검증된 호출을 실행 후 결과를 반환. 기획 단계에는 높은 thinking_level을, 실행 단계에는 중간 레벨을 사용하세요.

멀티모달 인제션 파이프라인

대형 문서, 이미지, 비디오를 전처리하고 인덱싱합니다.

언제 Gemini 3.1 Pro를 선택해야 하나요?

다음이 필요할 때 선택하세요:

멀티모달 입력 전반에 걸친 고정밀 다단계 추론;
신뢰할 수 있는 도구 오케스트레이션과 에이전트형 워크플로우;
IDE 내 더 나은 코드 생성/편집 루프(Copilot/CLI/Antigravity 경유);
CometAPI 같은 게이트웨이로 교차 공급자 비교를 빠르게 프로토타이핑.

처리량과 비용이 중요하다면 혼합 전략을 채택하세요: 대부분의 워크플로우에는 기본값으로 medium, 고처리량 사용자 채팅에는 low, 더 깊은 추론이 명백히 필요한 작업(기획, 증명, 다단계 합성)에만 high를 사용합니다.

마무리: 스택에서 Gemini 3.1 Pro의 위치

Gemini 3.1 Pro는 현대의 개발자 지향 LLM이 제공해야 할 핵심에 집중합니다: 멀티모달 이해, 명시적 도구 오케스트레이션, 그리고 추론 예산을 위한 실용적 제어. Google의 API와 Vertex를 통해 직접 접근하든, 프리미엄 플랜의 Copilot을 통해서든, CometAPI 같은 멀티 모델 플랫폼을 통해서든, 팀이 갖춰야 할 핵심 역량은 동일합니다: 세심한 thinking level 오케스트레이션, 안전한 함수 호출 패턴, 그리고 건전한 개발자 워크플로우(CLI, IDE, 자동 테스트)로의 통합.

개발자는 지금 CometAPI를 통해 Gemini 3.1 Pro에 접근할 수 있습니다. 시작하려면 Playground에서 모델의 기능을 탐색하고, 자세한 지침은 API guide를 참고하세요. 접근 전에 CometAPI에 로그인하고 API 키를 발급받았는지 확인하세요. CometAPI는 통합을 돕기 위해 공식 가격보다 훨씬 낮은 가격을 제공합니다.

Ready to Go?→ 오늘 바로 Gemini 3.1 Pro에 가입하세요 !

AI 관련 더 많은 팁, 가이드, 소식을 원하시면 VK, X, Discord를 팔로우하세요!