Gemini Decisions API를 사용하려면 Google AI Studio에서 API 키를 발급받고, google-genai 3.2 이상을 설치한 뒤, 모델 gemini-decision-1과 하나의 공유 input, 타입이 지정된 questions 맵(noul, choice, score)을 함께 넣어 client.decisions.create()를 호출하면 됩니다. 모든 질문에 대해 보정된 확률과 confidence가 반환되며, 출력 토큰은 0입니다.
아래에서는 첫 yes/no 질문부터 confidence 기반 라우팅, CI 테스트 스위트까지 Python, JavaScript, REST로 단계별로 살펴봅니다.
Gemini Decisions API란?
Gemini Decisions API는 Gemini Developer API(v1beta)의 엔드포인트로, 텍스트를 생성하는 대신 정답 집합이 정해진 질문에 답합니다. 하나의 멀티모달 입력과 최대 1,000개의 독립적인 질문을 보내면, 모델 gemini-decision-1이 단일 forward pass로 모든 옵션을 평가하고 코드에서 바로 분기에 사용할 수 있는 보정된 확률을 반환합니다.
Google은 2026년 11월 11일에 이를 발표했습니다. 공식 문서에서는 세 가지 질문 유형을 정의합니다:
| 질문 유형 | 용도 | 반환값 |
|---|---|---|
noul |
문장이 성립하는지 확인 (yes/no) | noul (0.01~0.99), confidence |
choice |
2~255개 옵션 중 하나 선택 | choice, probabilities, confidence |
score |
2~255개의 순서화된 등급으로 평가 | score, probabilities, legend, confidence |
Gemini API 가격 페이지에 따르면 입력 토큰 100만 개당 $0.10이며, 출력은 무료입니다. 공유 입력은 질문 수와 관계없이 요청당 한 번만 과금됩니다. 이미 OpenAI Decisions API 사용법 가이드를 읽으셨다면 구조가 익숙하게 느껴지실 텐데, 아래 필드들은 Gemini 고유의 것입니다.
1단계: API 키 발급 및 SDK 설치
- Google AI Studio를 열고 API 키를 생성합니다.
- 키를 내보냅니다:
export GEMINI_API_KEY="your-key" - SDK 3.2 이상을 설치합니다:
pip install -U google-genai또는npm install @google/genai@latest
코드 작성 전에 Decisions Playground에서 질문을 먼저 시험해 볼 수 있으며, 실행 가능한 코드도 내보낼 수 있습니다.
무료 등급, 2026년 11월 12일 확인 기준: rate limits 페이지에 따르면 무료 등급에서는 분당 200개 요청, 분당 50,000 토큰, 일일 10,000개 요청이 허용됩니다. 무료 등급에서는 입력이 무료이지만, 가격 페이지에서 무료 등급 데이터를 "제품 개선에 사용됨: 예"로 표시하고 있으므로 실제 고객 데이터는 유료 등급에서 처리하세요. Google의 무료 할당량에 대한 자세한 내용은 Gemini API 무료 등급 가이드를 참고하세요.
| 등급 | RPM | TPM | RPD |
|---|---|---|---|
| Free | 200 | 50,000 | 10,000 |
| Tier 1 | 1,500 | 1,000,000 | 50,000 |
| Tier 2 | 5,000 | 4,000,000 | 제한 없음 |
| Tier 3 | 15,000 | 10,000,000 | 제한 없음 |
2단계: 첫 noul(yes/no) 질문 보내기
noul 질문은 답이 "예"일 확률을 반환합니다. v1beta API 버전을 사용하는 점에 유의하세요. 이 엔드포인트는 v1에는 없습니다.
Python:
from google import genai
client = genai.Client(http_options={"api_version": "v1beta"})
result = client.decisions.create(
model="gemini-decision-1",
input="The blue mug I ordered on Monday arrived cracked on Wednesday.",
questions={
"is_damaged": {
"type": "noul",
"instructions": "Did the item arrive damaged?",
},
},
)
answer = result.answers["is_damaged"]
print(f"P(yes)={answer.noul:.2f} confidence={answer.confidence:.2f}")
JavaScript:
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiVersion: "v1beta" });
const result = await ai.decisions.create({
model: "gemini-decision-1",
input: "The blue mug I ordered on Monday arrived cracked on Wednesday.",
questions: {
is_damaged: { type: "noul", instructions: "Did the item arrive damaged?" },
},
});
const answer = result.answers?.is_damaged;
if (answer?.type === "noul") console.log(answer.noul, answer.confidence);
REST:
curl -X POST "https://generativelanguage.googleapis.com/v1beta/decisions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-decision-1",
"input": "The blue mug I ordered on Monday arrived cracked on Wednesday.",
"questions": {
"is_damaged": { "type": "noul", "instructions": "Did the item arrive damaged?" }
}
}'
Google 문서에 나온 응답 예시입니다(직접 실행한 결과가 아닌 문서의 예제입니다):
{
"answers": { "is_damaged": { "type": "noul", "noul": 0.99, "confidence": 0.99 } },
"usage": { "total_input_tokens": 100, "total_output_tokens": 0, "total_tokens": 100 }
}
"예"가 모호한 경우에는 true_description과 false_description이 담긴 criteria를 추가하세요. 기억해야 할 한 가지 규칙: noul 값은 항상 0.01과 0.99 사이이므로, 0.99를 넘는 임계값은 절대 일치하지 않습니다.
3단계: choice 및 score 질문 추가하기
동일한 입력에 대한 독립적인 질문들은 하나의 요청에 담을 수 있습니다. 입력은 한 번만 과금되고, 각 질문은 자신의 토큰만 추가됩니다.
result = client.decisions.create(
model="gemini-decision-1",
input="I was charged twice for my order and the export page crashes in Safari.",
questions={
"department": {
"type": "choice",
"instructions": "Which department should handle this request?",
"criteria": {
"billing": "Payments, invoices, and refunds.",
"technical": "Problems using the product.",
"shipping": "Delivery and tracking.",
"other": "Anything outside these categories.",
},
},
"severity": {
"type": "score",
"instructions": "How severe is this issue for the user?",
"criteria": [
"Cosmetic: appearance only, no lost functionality.",
"Workaround available: a task fails, but another way works.",
"Fully blocked: a task fails with no workaround.",
],
},
},
)
문서에서 사람들이 헷갈리는 세 가지 세부 사항:
- choice 키는 평가 전에 알파벳순으로 정렬됩니다. 포괄 옵션으로는 실제 옵션들보다 앞에 정렬되는
none_of_the_above대신other를 사용하세요. - score의 criteria는 리스트입니다. 낮은 등급에서 높은 등급 순으로, 인덱스는 0부터 시작합니다. 반환되는
score는 확률 가중 평균이므로 등급 사이의 값이 나올 수 있습니다(문서에는1.12가 예시로 나옵니다). - 모델은 질문 키를 절대 보지 못합니다. 전체 질문을
instructions에 작성하세요.
score에서 이산적인 등급을 얻으려면 가장 확률이 높은 항목을 선택하세요:
sev = result.answers["severity"]
level = max(sev.probabilities, key=sev.probabilities.get)
print(sev.legend[level])
4단계: 이미지, PDF, 오디오 보내기
input은 문자열, 하나의 콘텐츠 블록, 또는 블록 리스트를 받을 수 있으며, Interactions API와 동일한 블록 형식을 사용합니다. 지원되는 블록은 text, image, audio, video, document(PDF만)입니다.
import base64
with open("earcup.jpg", "rb") as f:
image_b64 = base64.b64encode(f.read()).decode("utf-8")
with open("return-form.pdf", "rb") as f:
pdf_b64 = base64.b64encode(f.read()).decode("utf-8")
result = client.decisions.create(
model="gemini-decision-1",
input=[
{"type": "text", "text": "Customer photo and form for return #8821.\n"},
{"type": "image", "data": image_b64, "mime_type": "image/jpeg", "resolution": "low"},
{"type": "document", "data": pdf_b64, "mime_type": "application/pdf"},
],
questions={
"visible_damage": {
"type": "noul",
"instructions": "Does the photo show physical damage to the device? Ignore the packaging.",
},
"form_signed": {
"type": "noul",
"instructions": "Is the return form in the PDF signed by the customer?",
},
},
)
오디오의 경우 {"type": "audio", "uri": "<https-url>", "mime_type": "audio/mp3"} 같은 블록을 전달하세요. 알아두면 유용한 제한 사항:
- 인라인 base64 데이터는 요청당 100 MB(PDF는 50 MB)로 제한되며, 외부 URL은 각각 15 MB입니다.
- 실제 MIME 타입을 지정하세요. API는
application/octet-stream을 거부합니다. - YouTube URL과
gs://URI는 지원되지 않습니다. Files API, 공개 또는 서명된 HTTPS URL, 또는 인라인 바이트를 사용하세요. resolution(low,medium,high,ultra_high)는 시각적 디테일과 토큰 수를 절충합니다.ultra_high는 이미지 전용입니다.
5단계: 확률과 confidence 읽기
모든 답변에는 0부터 1 사이의 confidence가 포함되며, 이는 최상위 답변이 맞을 추정 확률입니다. choice와 score의 경우 최상위 결과의 확률과 같고, noul의 경우 max(noul, 1 - noul)입니다.
따라서 noul이 0.03이면 confidence는 0.97입니다. 즉, 모델은 답이 "아니오"라고 확신하는 것입니다.
6단계: 낮은 confidence 답변을 폴백으로 라우팅하기
값으로 작업을 선택하고, confidence로 자동 실행 여부를 판단하세요:
a = result.answers
dept = a["department"]
if dept.confidence >= 0.7 and dept.choice != "other":
route_to(dept.choice)
elif dept.confidence >= 0.4:
route_to_fallback_model(ticket) # a bigger model reasons it out
else:
route_to("human_review")
0.7과 0.4라는 컷오프는 예시일 뿐입니다. Google은 자체 트래픽의 레이블이 지정된 예시를 바탕으로 임계값을 설정하도록 권고합니다. 문서의 규칙 두 가지가 더 있습니다:
- choice 질문은 어떤 옵션도 맞지 않더라도 항상 확률을 여러 옵션에 분배합니다. "이 메시지는 주문에 관한 것인가요?" 같은 범위 확인 질문과 함께 사용하세요.
- 입력은 신뢰할 수 없는 것으로 취급하세요. 사용자 메시지가 자신의 분류를 유도할 수 있습니다. 지급 처리 등 결과가 중대한 작업에는 사람의 확인이나 이중 검증을 유지하세요.
7단계: Apidog CLI로 코딩 에이전트가 테스트하게 하기
라우팅 레이어는 조용히 실패합니다. 누군가 기준 문구를 바꾸면 티켓의 절반에서 billing이 technical로 바뀌어도 아무 오류도 발생하지 않습니다. 해결책은 기대되는 결정을 고정하는 회귀 테스트 스위트이며, 코딩 에이전트가 Apidog CLI로 이를 구축하도록 하고 여러분은 검토만 하면 됩니다.
npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com # pick your agent when prompted
그다음 에이전트에 프롬프트 하나를 주세요:
In Apidog project <id>, build a test suite for POST
https://generativelanguage.googleapis.com/v1beta/decisions (header x-goog-api-key
from env var GEMINI_API_KEY). Add one request per question type (noul, choice,
score) asserting status 200, confidence between 0 and 1 and zero output tokens.
Add a test data set of 20 tickets with expected departments and assert each
choice matches with confidence >= 0.7. Run it and summarize failures.
에이전트가 각 페이로드 스키마를 읽고 검증한 뒤 리소스를 작성하고 스위트를 실행합니다:
apidog cli-schema get test-scenario-create
apidog cli-schema validate test-scenario-create --file scenario.json
apidog test-scenario create --project <id> --file scenario.json
apidog test-data create --project <id> --file tickets.json
apidog test-suite create --project <id> --file suite.json
apidog run --test-suite <suiteId> --project <id> -e <envId> -d <testDataId> -r cli,junit --out-dir reports
위의 모든 플래그는 CLI 2.2.12의 apidog run --help에서 가져온 것입니다. 이제 fixture의 결정을 뒤집는 프롬프트나 criteria 변경이 실행을 실패시킵니다. 동일한 apidog run ... -r cli,junit을 GitHub Actions에 넣으면 JUnit 파일에서 어떤 티켓이 뒤집혔는지 확인할 수 있습니다. Apidog CLI CI/CD 가이드에 워크플로우 파일이 있고, Claude Code에서의 Apidog CLI에서 에이전트 설정을 다룹니다. Apidog의 Free 플랜은 최대 4명의 사용자까지 지원합니다.
제한 사항과 아직 지원되지 않는 기능
Decisions API 제한 사항에서, 2026년 11월 12일 확인 기준:
- 요청당 1~1,000개의 질문, 262,144 토큰 컨텍스트 창 내에서.
- 컨텍스트 캐싱, Batch API, Flex 또는 Priority 추론은 지원되지 않습니다. 요청 간 반복 입력은 전액 과금됩니다.
- 안전성 차단 시 답변 대신
safety나prohibited_content같은error.code와 함께 HTTP 400이 반환됩니다. - Gemini Developer API(
v1beta)만 지원됩니다. Google은 Vertex AI 지원이 "곧 제공될 예정"이라고 하지만 날짜는 밝히지 않았습니다.
Google은 엔드투엔드 지연 시간이 150~250 ms이며, 16K 토큰까지의 입력에서 질문 1개부터 100개까지 거의 일정하다고 보고하고, Gemini Decision 1이 자체 벤치마크 스위트에서 가장 낮은 보정 오차로 선두라고 밝혔습니다. 이는 Google의 수치이므로, 이를 기반으로 설계하기 전에 자체 입력으로 지연 시간을 측정하세요.
FAQ
Gemini Decisions API는 무료인가요? 입력이 무료인 Free 등급이 있으며, 분당 200 요청, 분당 50,000 토큰, 일일 10,000 요청으로 제한됩니다(2026년 11월 12일 확인 기준). Free 등급 데이터는 Google 제품 개선에 사용될 수 있습니다. 유료 등급은 입력 토큰 100만 개당 $0.10입니다.
noul은 무슨 뜻인가요? yes/no 질문 유형입니다. noul 필드는 답이 "예"일 확률이며, 0.01에서 0.99 사이의 값입니다.
어떤 API 버전을 사용해야 하나요? v1beta입니다. Python에서는 http_options={"api_version": "v1beta"}를, JavaScript에서는 apiVersion: "v1beta"를 설정하거나, REST에서는 /v1beta/decisions를 호출하세요.
Vertex AI에서도 작동하나요? 아직은 아닙니다. Gemini Developer API에서만 제공되며, Google은 Google Cloud의 Gemini를 곧 제공될 예정으로 표시하고 있습니다.
confidence 임계값은 어떻게 정하나요? 실제 입력 몇백 개에 레이블을 붙여 API로 실행한 뒤, 잘못된 자동 작업의 비용과 사람의 검토 비용이 같아지는 지점을 컷오프로 선택하세요.