Gemini 설정

대시보드에서 API 키를 만들고 Gemini 채널을 선택하세요. 채널은 구매한 쿼터의 소비 속도만 0.625배로 바꾸며, 구매한 쿼터 자체는 바꾸지 않습니다.

이 채널에서는 클라이언트가 선언하고 실행하는 함수를 사용할 수 있습니다. Google 검색 및 지도 같은 호스팅 도구를 요청하면 전달 전에 HTTP 400이 반환됩니다. 유효한 응답 내용은 도착하는 대로 전달하며, 업스트림이 보고한 사용량에 따라 과금합니다. 명시적인 cachedContent 참조에는 도구 정의가 포함될 수 있어 차단됩니다. 암시적 캐싱은 사용할 수 있습니다.

생성 요청에는 표준 서비스 등급을 사용합니다. 요금이 설정되지 않은 등급이나 fileData로 원격 파일을 지정하면 HTTP 400이 반환됩니다. 본문에 모델을 지정할 때는 URL의 모델과 일치해야 합니다. 같은 키로 countTokens를 호출하면 생성 할당량을 사용하지 않고 텍스트와 인라인 미디어의 토큰 수를 확인할 수 있습니다.

사용 가능한 모델은 GET /v1beta/models로 확인할 수 있습니다.

API 키와 결제에 사용하는 잔액이 모두 0보다 크면 생성 요청을 보냅니다. 요청에 설정한 출력 및 도구 한도는 그대로 전달하고 실제 사용량으로 정산합니다. 동시 요청으로 잔액이 음수가 될 수 있습니다.

지원 모델

gemini-4-carbon을 사용할 수 있습니다. 기본 모델은 gemini-3.5-flash로 유지되며 gemini-3.7-flash와 gemini-3.8-flash도 계속 지원합니다. AWSQ, CCMAX, Codex 키로는 Gemini 모델을 호출할 수 없습니다. 가격 단위는 백만 토큰당 USD입니다. GPT 모델이 필요하다면 Codex 키를 사용하세요. GPT-6.1 Sol과 Terra에서 이 두 GPT-6.1 모델을 비교합니다.

Carbon은 공식 출시 요금을 따릅니다. Google은 시간대 없이 날짜만 명시하므로 본 서비스는 2026-12-01 00:00 UTC에 요금을 전환합니다. 출력에는 사고 토큰이 포함됩니다.

Gemini 채널에서 gemini-4-carbon도 사용할 수 있습니다. 현재 입력·캐시 읽기·출력 요금은 실시간 요금표에서 Gemini를 선택해 확인하세요. Carbon은 2026-12-01 00:00 UTC 전까지 설정된 정규 기본 요금의 50%, 이후에는 정규 요금으로 계산합니다. 표에는 할인과 채널 계수가 반영되어 있습니다.

Gemini CLI

공식 Gemini CLI 설치 안내에 따라 Node.js 20.0.0 이상이 필요합니다. 먼저 버전을 확인하세요.

1
node --version

Node.js가 없거나 20.0.0 미만이면 지원되는 버전을 먼저 설치하세요. 아래 설정은 Gemini CLI 0.67.0에서 확인했습니다. 같은 절차를 따르려면 이 버전을 설치하세요.

1
npm install -g @google/[email protected]
2
gemini --version

프로젝트 설정

프로젝트 디렉터리에 .gemini/settings.json을 만드세요. 파일이 이미 있으면 아래 필드를 병합하고 customOverrides 항목을 기존 배열에 추가하세요. API 키는 환경 변수로 전달하며 이 파일에 저장하지 않습니다.

1
{
2
  "security": { "auth": { "selectedType": "gemini-api-key" } },
3
  "model": { "name": "gemini-3.8-flash" },
4
  "modelConfigs": {
5
    "customOverrides": [
6
      {"match": {"model": "base"}, "modelConfig": {"model": "gemini-3.8-flash"}},
7
      {"match": {"model": "gemini-3-pro-preview"}, "modelConfig": {"model": "gemini-3.8-flash"}},
8
      {"match": {"model": "gemini-3-flash-preview"}, "modelConfig": {"model": "gemini-3.8-flash"}},
9
      {"match": {"model": "gemini-3.1-flash-lite"}, "modelConfig": {"model": "gemini-3.8-flash"}},
10
      {"match": {"model": "gemini-2.5-pro"}, "modelConfig": {"model": "gemini-3.8-flash"}},
11
      {"match": {"model": "gemini-2.5-flash"}, "modelConfig": {"model": "gemini-3.8-flash"}},
12
      {"match": {"model": "gemini-2.5-flash-lite"}, "modelConfig": {"model": "gemini-3.8-flash"}}
13
    ]
14
  },
15
  "agents": {
16
    "overrides": {
17
      "codebase_investigator": { "modelConfig": { "model": "gemini-3.8-flash" } }
18
    }
19
  },
20
  "tools": { "exclude": ["google_web_search", "web_fetch"] }
21
}

이 설정은 API 키 인증을 사용하고 주 대화, 내장 보조 요청, 컨텍스트 압축, 코드베이스 조사 하위 에이전트의 모델을 gemini-3.8-flash로 지정합니다. --model만으로 모든 보조 모델이나 하위 에이전트 모델이 바뀌지는 않습니다. 이 채널에서 지원하지 않는 호스팅 Google 검색과 URL 컨텍스트 도구는 제외합니다. 로컬 파일과 shell 도구는 계속 사용할 수 있습니다.

프로젝트 디렉터리에서 실행

자리표시자를 대시보드에서 만든 Gemini 키로 바꾸세요. 처음 실행할 때 CLI 안내에 따라 프로젝트를 신뢰하면 프로젝트 설정을 불러옵니다.

1
export GEMINI_API_KEY="YOUR_DASHBOARD_API_KEY"
2
export GOOGLE_GEMINI_BASE_URL='https://api.aiinide.com'
3
gemini --model gemini-3.8-flash

모델을 명시하는 옵션을 유지하세요. 프로젝트 설정 없이 gemini를 실행하면 서비스의 기본 모델이 아닌 클라이언트의 Auto 라우팅이 적용됩니다. CLI 업그레이드, 모델 변경, 사용자 지정 에이전트나 확장 기능 추가 시 해당 모델 설정도 확인하세요. Model "…" is not configured 오류가 나면 표시된 모델 이름과 로드된 설정을 확인하세요. 자세한 내용은 공식 모델 설정 및 하위 에이전트 설정 안내를 참고하세요.

클라이언트에는 대시보드에서 만든 키만 사용하고 서버의 upstream GEMINI_API_KEY는 사용하지 마세요.

일반 요청

이 예제에는 설명할 코드 전체가 포함되어 있으며 로컬 파일을 읽지 않습니다. 자리표시자를 대시보드에서 만든 Gemini 키로 바꾸고 Bash 호환 셸에서 실행하세요. 아래의 일반 요청과 스트리밍 요청은 모두 실제 사용량에 따라 쿼터를 소비합니다.

1
export GEMINI_API_KEY="YOUR_DASHBOARD_API_KEY"
2
 
3
curl --globoff --fail-with-body 'https://api.aiinide.com/v1beta/models/gemini-3.8-flash:generateContent' \
4
  -H "x-goog-api-key: $GEMINI_API_KEY" \
5
  -H "Content-Type: application/json" \
6
  -d '{"contents":[{"role":"user","parts":[{"text":"이 JavaScript 함수의 반환값을 한 문장으로 설명해 주세요: function add(a, b) { return a + b; }"}]}]}'

candidates[].content.parts[].text에 답변이 있고 해당 후보의 finishReason이 "STOP"인지 확인하세요. 예를 들어 “두 숫자를 더하며, 둘 중 하나가 문자열이면 문자열을 이어 붙입니다.”라는 답변이 나옵니다. 표현은 달라질 수 있습니다. 답변이 없으면 promptFeedback과 finishReason을 확인하세요. MAX_TOKENS는 출력 한도에 도달했다는 뜻입니다. 실제 사용량은 사용 내역에서 확인할 수 있습니다.

스트리밍 요청

위에서 설정한 키를 사용하세요. generateContent를 streamGenerateContent로 바꾸고 ?alt=sse와 curl -N으로 도착하는 청크를 바로 표시합니다.

1
curl --globoff --fail-with-body -N 'https://api.aiinide.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse' \
2
  -H "x-goog-api-key: $GEMINI_API_KEY" \
3
  -H "Content-Type: application/json" \
4
  -d '{"contents":[{"role":"user","parts":[{"text":"이 JavaScript 함수의 반환값을 한 문장으로 설명해 주세요: function add(a, b) { return a + b; }"}]}]}'

응답은 SSE data: 이벤트로 도착합니다. candidates[].content.parts[].text의 답변 청크를 순서대로 읽고 해당 후보가 finishReason: "STOP"으로 끝나는지 확인하세요. 같은 함수에 대한 설명이 나와야 합니다. HTTP 200이나 첫 텍스트 청크만으로 완료를 판단할 수 없습니다. 연결이 끊기거나 다른 종료 사유가 나오면 내용을 확인하세요.

Gemini 클라이언트가 Base URL 뒤에 /v1beta/models/...를 붙입니다. 기존 Base URL의 /api/codex 및 /api/gemini 접두사도 기존 키로 계속 사용할 수 있습니다.

401은 키 문제, 400은 채널 또는 모델 문제, 429는 한도 초과, 503은 upstream 일시 장애를 뜻합니다.