제미나이 Batch API로 비용 줄이는 법: 실시간 호출과 요금 비교·JSONL 일괄 처리

제미나이 Batch API는 즉시 응답이 필요 없는 대량 요청을 비동기로 처리해, 같은 모델의 표준 호출 대비 토큰 비용을 50%로 줄이는 기능이다. 문서 분류나 요약 결과를 나중에 받아도 된다면 검토할 만하다. 다만 비용 절감만큼 중요한 조건이 있다. Google이 안내하는 24시간은 처리 목표 시간이며, 완료를 보장하는 마감 시간이 아니다.

이 주제의 중심은 실제 적용 방법을 찾는 탐색형 검색 의도다. 따라서 처리 방식의 차이를 먼저 확인하고, 동일 토큰량으로 비용을 계산한 뒤 JSONL 제출부터 결과 확인까지 이어지는 순서로 정리한다. 요금 기준일은 2026년 10월 26일이며, 아래 단가는 Gemini Developer API 유료 요금 기준이다.

제미나이 Batch API와 실시간 호출 비교: 어떤 작업에 적합할까

실시간 호출은 요청한 자리에서 결과를 받아 다음 동작을 이어가는 방식이다. Batch API는 요청들을 작업으로 제출하고, 처리 상태를 확인한 뒤 결과를 회수하는 방식이다. 채팅 응답처럼 대기 시간이 사용자 경험에 직접 영향을 주는 기능과, 밤사이 끝내도 되는 문서 처리는 선택 기준이 달라진다.

예를 들어 하루 동안 쌓인 문서를 다음 업무 시간 전에 분류하는 흐름은 Batch 도입 후보가 된다. 반면 문서를 올린 직후 요약 화면을 보여줘야 한다면 실시간 호출이 자연스럽다. 같은 서비스에서도 즉시 처리와 정기 처리를 나누는 설계가 가능하다.

출처: Google 공식 Batch API 문서. 처리 방식과 50% 비용, 24시간 목표 시간에 관한 설명을 기준으로 비교했다.

제미나이 Batch API와 실시간 호출 비교: 어떤 작업에 적합할까 실시간 확인하기

Gemini 3.8 Flash 요금 비교와 동일 토큰량 비용 계산

할인율은 반드시 동일 모델·동일 입력 토큰량·동일 과금 대상 출력 토큰량으로 비교해야 한다. 2026년 12월 31일까지 Gemini 3.8 Flash의 100만 토큰당 표준 입력 요금은 0.75달러, 출력 요금은 3.75달러다. Batch는 각각 0.375달러와 1.875달러이며, 출력 요금에는 사고 토큰이 포함된다.

계산 조건을 입력 1,000만 토큰, 사고 토큰을 포함한 출력 200만 토큰으로 두면 차이가 분명해진다. 이는 실제 고객의 사용 통계가 아니라, 공식 단가에 동일 사용량을 대입한 비용 예시다. 캐싱·검색 도구 등의 추가 과금과 세금, 환율은 계산에서 제외했다.

• 2026년 표준: 10 × $0.75 + 2 × $3.75 = $15
• 2026년 Batch: 10 × $0.375 + 2 × $1.875 = $7.50
• 차액: $7.50, 절감률: ($15 − $7.50) ÷ $15 = 50%

같은 사용량을 2027년 공지 단가에 대입하면 표준은 30달러, Batch는 15달러다. 할인율이 유지돼도 실제 지출은 달라지므로, 연도를 넘기는 예산은 적용 날짜별로 나눠 계산해야 한다. 근거: Google 공식 Gemini Developer API 요금표, Gemini 3.8 Flash 항목.

Gemini 3.8 Flash 표준·Batch 적용 기간별 요금 실시간 확인하기

JSONL 일괄 처리 준비: key와 request를 한 줄에 작성하기

제출 방식은 인라인과 파일 두 가지다. 전체 요청 크기가 20MB 미만인 소규모 작업은 인라인이 간단하고, 큰 작업은 JSONL 입력 파일 방식이 권장된다. 파일 방식의 입력 파일 최대 크기는 2GB다.

JSONL은 JSON 배열과 다르다. 각 줄이 독립된 JSON 객체여야 하며, 줄마다 사용자 지정 key와 유효한 GenerateContentRequest를 담은 request가 들어간다. 다음은 Google 공식 예제의 구조를 문서 분류·요약 용도로 바꾼 예시다.

{"key":"doc-001","request":{"contents":[{"role":"user","parts":[{"text":"다음 문서를 계약·청구·기타 중 하나로 분류하라: 이번 달 서비스 이용료 청구서입니다."}]}]}}
{"key":"doc-002","request":{"contents":[{"role":"user","parts":[{"text":"다음 문서를 한 문장으로 요약하라: 시스템 정기 점검은 토요일 새벽에 진행하며 점검 중 접속이 제한됩니다."}]}]}}

위 내용을 UTF-8 형식의 requests.jsonl 파일로 저장한다. 예제는 두 줄이며, 각 줄 사이에 쉼표를 넣거나 전체를 대괄호로 감싸지 않는다. 문서 원문에 줄바꿈이 들어간다면 직접 문자열을 이어 붙이기보다 JSON 직렬화 기능으로 이스케이프하는 편이 안전하다.

key는 결과를 원본 문서와 연결하는 기준이므로 문서 식별자를 바탕으로 중복 없이 부여하는 것이 좋다. 분류와 요약을 같은 문서에 각각 실행한다면 doc-001-classify, doc-001-summary처럼 작업 목적까지 구분할 수 있다. 결과는 줄 순서보다 키를 기준으로 연결하도록 설계한다.

JSONL 일괄 처리 준비: key와 request를 한 줄에 작성하기

Batch 작업 생성·상태 조회·결과 회수 Python 절차

다음 코드는 Google Gen AI Python SDK의 공식 사용 흐름을 바탕으로 구성했다. google-genai 패키지를 설치하고 GEMINI_API_KEY 환경 변수를 설정한 뒤, 앞에서 저장한 파일이 있는 경로에서 실행한다. API 키는 코드나 JSONL 파일에 넣지 않는다.

1. 입력 검증: 각 줄이 JSON으로 해석되는지, key가 중복되지 않는지 확인한다.
2. 파일 업로드: File API에 JSONL을 올린다.
3. 작업 생성: 업로드한 파일 이름을 입력 소스로 지정한다.
4. 상태 조회: 생성된 작업 이름으로 종료 상태를 확인한다.
5. 결과 회수: 성공한 파일 작업의 출력 JSONL을 다운로드한다.

import time
from pathlib import Path
from google import genai
from google.genai import types

client = genai.Client()

uploaded = client.files.upload(
    file="requests.jsonl",
    config=types.UploadFileConfig(mime_type="jsonl"),
)

job = client.batches.create(
    model="gemini-3.8-flash",
    src=uploaded.name,
    config={"display_name": "document-processing"},
)
print("저장할 작업 이름:", job.name)

terminal_states = {
    "JOB_STATE_SUCCEEDED",
    "JOB_STATE_FAILED",
    "JOB_STATE_CANCELLED",
    "JOB_STATE_EXPIRED",
}

while job.state.name not in terminal_states:
    time.sleep(30)
    job = client.batches.get(name=job.name)

print("종료 상태:", job.state.name)

if job.state.name == "JOB_STATE_SUCCEEDED":
    if job.dest and job.dest.file_name:
        result = client.files.download(file=job.dest.file_name)
        Path("results.jsonl").write_bytes(result)
        print("results.jsonl 저장 완료")
    else:
        print("출력 파일 정보를 확인하세요.")
else:
    print("작업 오류:", job.error)

운영 환경에서는 출력한 job.name을 별도로 저장해야 한다. 프로그램이 종료되더라도 이 이름으로 상태 조회를 재개할 수 있어, 확인 없이 같은 입력을 다시 제출하는 일을 줄일 수 있다. 예제의 30초는 조회 간격이며 실제 처리 시간을 뜻하지 않는다.

계속 실행되는 대기 루프가 부담스럽다면 작업 생성과 상태 조회를 별도 프로그램으로 나누는 방법도 있다. 주기적으로 상태를 확인하고 완료된 작업만 내려받도록 구성하면, 제출 프로그램을 장시간 켜 둘 필요가 없다. 근거: Google 공식 Batch API 문서의 Python 작업 생성·상태 조회·결과 회수 예제.

지원 모델·24시간 대기·개별 요청 실패 확인 기준

예제에서 사용한 모델은 gemini-3.8-flash다. 다른 모델로 바꾸기 전에는 Google 모델 문서의 Batch 지원 여부와 해당 모델의 요금표를 함께 확인해야 한다. 현재 안내된 Batch 기능 범위는 generateContent이며, 다른 API 기능까지 동일하게 사용할 수 있다고 가정하면 안 된다.

파일 방식의 결과는 JSONL이며, 각 줄에는 응답 또는 상태 객체가 들어간다. 따라서 작업 전체의 종료 상태를 확인한 뒤에도 개별 줄을 검사해야 한다. 정상 응답이 있는지, 오류나 상태 정보가 있는지, 생성된 내용이 요구한 분류·요약 형식에 맞는지를 순서대로 살펴본다.

• 수량 대조: 제출한 key 목록과 결과 key 목록을 비교해 누락·중복을 찾는다.
• 개별 오류 분리: 성공 응답과 실패 항목을 따로 기록한다.
• 내용 검수: 응답이 있어도 빈 내용이나 예상과 다른 분류값은 별도로 처리한다.
• 선별 재제출: 원인을 수정한 실패 항목만 새 JSONL로 구성한다.

Batch를 429 오류의 일괄 해결책으로 보는 접근도 피해야 한다. 처리 방식을 비동기로 바꾸는 것과 프로젝트의 사용 한도·권한·입력 오류를 해결하는 것은 별개의 문제다. 제출이나 조회에서 오류가 발생하면 해당 응답을 확인하고, 재시도 가능한 오류인지 먼저 구분해야 한다.

문서 분류·요약 비용을 줄이는 Batch 전환 체크리스트

운영 관점에서 핵심은 할인율보다 결과를 기다릴 수 있는 업무 범위다. 즉시성이 필요 없는 요청을 분리하고, 결과 연결과 실패 재처리를 자동화할 수 있을 때 토큰 비용 절감이 실제 운영 효율로 이어진다. 반대로 소량 작업마다 사람이 업로드·다운로드·검수를 반복하면 관리 부담이 절감액보다 커질 수 있다.

요약 작업은 출력 길이와 사고 토큰까지 비용에 영향을 주므로, Batch 전환 전후의 실제 사용량도 함께 기록하는 편이 좋다. 동일한 문서 표본과 생성 조건을 사용하고 분류 정확도, 요약의 필수 정보 누락, 완료 시각, 재처리 건수를 비교하면 도입 판단이 선명해진다. 이는 성능 향상을 보장하는 통계가 아니라 적용 전에 확인할 운영 지표다.

• 결과가 즉시 필요하지 않고, 목표 시간보다 늦어질 가능성을 업무에서 수용할 수 있는가?
• 선택한 모델의 Batch 지원과 적용 날짜별 유료 단가를 확인했는가?
• JSONL 유효성, 파일 크기, key 중복을 제출 전에 검사하는가?
• 작업 이름을 저장하고 종료 상태와 개별 결과를 모두 확인하는가?
• 실패 항목만 재제출하고, 실제 과금 토큰량으로 절감액을 계산하는가?

처음에는 대표 문서 소량으로 제출부터 결과 회수까지 한 번 완주하는 것이 좋다. 그다음 대기 시간을 허용하는 정기 작업으로 범위를 넓히면 된다. 제미나이 Batch API의 비용 이점을 살리는 출발점은 동일 모델의 정확한 단가 비교와, 실패한 요청까지 추적할 수 있는 JSONL 처리 흐름이다.