얼리버드 가격(12월 25일까지), 구독을 유지하는 동안 계속 적용: Go 월 $10(정가 $20), Opus 5.5를 쓰는 Plus 월 $30(정가 $50)지금 구독하기 →

Gemini API 오피스 파일: docx·xlsx·pptx 직접 업로드하고 필요한 부분만 처리하기

Gemini API를 호출할 때마다 엑셀 파일을 CSV로 변환하고 있었다면 이제 그 작업을 멈춰도 됩니다. 2026년 11월 18일부터 Gemini API는 Word, Excel, PowerPoint 파일을 직접 받아 처리하며, Google은 선택한 범위만 "처리하고 비용을 지불"할 수 있다고 설명합니다(Google AI Studio 변경사항).

다만 비용을 줄이려면 범위 선택자를 직접 지정해야 합니다. 그렇지 않으면 파일 전체가 처리될 수 있습니다. 독자 @zg0820도 이 점을 지적했습니다.

기존 Excel 처리 방식이 불편했던 이유

기존 문서에 안내된 방식은 XLSX 파일의 첫 번째 워크시트만 CSV로 읽는 것이었습니다. 여러 시트를 다뤄야 한다면 시트 순서를 바꾸거나 파일을 나눌 수밖에 없었죠.

"문서에는 아직도 XLSX의 첫 번째 시트만 CSV로 읽는다고 나와 있습니다." — @aitrackerbot

2026년 11월 18일 변경사항은 이 우회 작업을 없앴습니다. 이제 Office 및 OpenDocument 파일을 직접 입력할 수 있고, 프롬프트와 함수 응답에서 처리할 범위도 지정할 수 있습니다(DocsWatch 분석).

2026년 11월 18일 Office 파일 및 콘텐츠 슬라이싱 항목을 보여주는 Gemini API 변경사항

2026년 11월 18일 업데이트의 핵심

이번 변경은 11월 5일 PPT, ODP, ODS 지원 확대에 이어 두 가지 기능을 추가합니다.

  1. Office 및 OpenDocument 파일 직접 입력. Word, PowerPoint, Excel 파일을 PDF나 텍스트로 변환하지 않고 바로 전달할 수 있습니다.
  2. 콘텐츠 범위 지정. 페이지 범위, 워크시트 탭, A1 셀 범위, 시간 구간은 물론 페이지 이미지, 추출 텍스트, 수식, 트랜스크립트 같은 콘텐츠 레이어까지 선택할 수 있습니다.

범위 지정은 프롬프트뿐 아니라 FunctionResponse 파트에서도 작동합니다. 따라서 도구가 통합 문서 전체가 아닌 특정 시트의 일부 범위만 반환하도록 만들 수 있습니다(AI Index 요약).

지원 파일과 모델 범위

2026년 11월 18일 UTC에 업데이트된 Firebase 입력 요구사항 문서는 Office 지원 대상이 Gemini 4.x 모델이라고 설명합니다(Firebase AI Logic 문서).

제품군확장자MIME 타입
Word.doc, .docx, .dotxapplication/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.openxmlformats-officedocument.wordprocessingml.template
PowerPoint.ppt, .pptxapplication/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation
Excel.xls, .xlsxapplication/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
OpenDocument.odt, .odp, .odsapplication/vnd.oasis.opendocument.text, application/vnd.oasis.opendocument.presentation, application/vnd.oasis.opendocument.spreadsheet
기본 지원.pdf, .txtapplication/pdf, text/plain

공식 제한사항은 다음과 같습니다. 범위 지정 기능이 이 한도를 늘려주지는 않습니다.

  • 파일당 50MB, 파일당 1,000페이지, 요청당 문서 파일 3,000개.
  • 인라인 base64 데이터의 전체 요청 크기 20MB; 더 큰 파일은 Cloud Storage URL을 사용해야 합니다.

확인되지 않은 커뮤니티 제보는 별도로 봐야 합니다. 한 변경사항 독자는 Office 파일에 약 2,000페이지 또는 슬라이드 제한이 있다고 전했습니다(@lawson_ste3476). Google이 공식 문서로 확인한 내용은 아니므로 이 제한을 기준으로 설계해서는 안 됩니다.

Word와 PowerPoint: 페이지 범위와 콘텐츠 레이어

DocumentMetadata는 공개된 v1beta/v1alpha Discovery 문서에서 확인됐지만, 안정 버전인 v1에는 없습니다(ORIENS 스키마 보고서).

  • startPage: 시작 페이지. 1부터 세며 해당 페이지를 포함합니다.
  • endPage: 마지막 페이지. 1부터 세며 해당 페이지를 포함합니다.
  • contentLayers: PAGE_IMAGE(렌더링된 이미지; 메타데이터는 있지만 레이어가 비어 있을 때 보고된 기본값) 또는 PAGE_TEXT(추출된 텍스트).

레이아웃, 슬라이드, 스캔 문서라면 PAGE_IMAGE를 선택하고, 계약서처럼 검색 가능한 텍스트가 필요하다면 PAGE_TEXT를 선택하면 됩니다. Firebase 문서에 따르면 PDF는 페이지당 이미지 하나로 처리되며, 가로와 세로가 모두 384px 이하인 이미지는 258토큰으로 계산됩니다(Firebase AI Logic 문서).

Excel: 시트, 셀 범위, 세 가지 레이어 모드

Discovery 스키마에 따르면 SpreadsheetMetadata는 inline_data 또는 file_data로 전달된 파일 파트에 연결됩니다. 입력 Part나 FunctionResponsePart에서 사용할 수 있습니다(ORIENS 스키마 보고서).

  • sheetIndex: 통합 문서 내 순서이며 1부터 시작합니다. Discovery v1beta 문서에는 생략하면 모든 시트를 사용한다고 되어 있지만, Python과 JavaScript SDK 문서에는 첫 번째 시트라고 적혀 있습니다. 매번 직접 지정하는 편이 안전합니다.
  • visibleCells: A1:G35 같은 A1 범위입니다. 생략하면 선택한 시트에서 실제로 사용된 영역이 대상이 됩니다.
  • contentLayers: DATA(값, 병합, 서식), FORMULAS(수식과 계산 결과), VISUAL(렌더링된 이미지)로 구성됩니다. 보고된 기본값은 [DATA, FORMULAS]입니다.

감사 작업에는 DATA와 FORMULAS를 사용하고, 레이아웃이나 병합 셀의 맥락이 필요하면 VISUAL을 추가하세요. 단일 값을 조회할 때는 visibleCells 범위를 최대한 좁히는 것이 좋습니다.

필요한 범위만 보내기: Python REST 예제

아래 필드 이름은 Discovery revision 20261116에 맞춰져 있습니다. 아직 베타 형태이고 안정 버전인 v1에는 없으므로, 운영 환경에 적용하기 전에 설치한 SDK와 실제 지원 여부를 확인해야 합니다.

python
import os
from google import genai
import requests

client = genai.Client()  # reads GEMINI_API_KEY
workbook = client.files.upload(
    file="q3_revenue.xlsx",
    config={"mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"},
)

api_key = os.environ["GEMINI_API_KEY"]
url = f"https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent?key={api_key}"
payload = {
    "contents": [{
        "parts": [
            {
                "fileData": {
                    "fileUri": workbook.uri,
                    "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
                },
                "spreadsheetMetadata": {
                    "sheetIndex": 2,
                    "visibleCells": "A1:G35",
                    "contentLayers": ["DATA", "FORMULAS"],
                },
            },
            {"text": "Summarize revenue variance in this range using computed values."},
        ]
    }]
}
r = requests.post(url, json=payload, timeout=120)
r.raise_for_status()
print(r.json()["candidates"][0]["content"]["parts"][0]["text"])

Word 파일은 .docx MIME 타입과 함께 "documentMetadata": {"startPage": 12, "endPage": 18, "contentLayers": ["PAGE_TEXT"]}를 사용하면 됩니다. PowerPoint도 같은 documentMetadata 형식을 사용하며, .pptx MIME 타입과 슬라이드 페이지 번호를 지정합니다.

비용 계산: 범위 지정이 실제로 절약되는 경우

변경사항 문서나 Firebase 가격 안내에는 범위 지정 전용 SKU가 없습니다. 따라서 절약되는 금액은 표준 요율에서 입력 토큰을 얼마나 줄였는지에 따라 결정됩니다. 변경사항에는 gemini-4-hydrogen의 입력 토큰 가격이 100만 토큰당 $1.50이라고 나와 있습니다.

예를 들어 200페이지 보고서에서 12~18페이지만 필요하다고 가정해 보겠습니다. 아래에서 텍스트 페이지당 800토큰이라는 수치는 공식 요율이 아닌 예시용 가정입니다.

  • 기존 방식: 페이지 이미지 200개 x 페이지 이미지당 최소 258토큰 = 입력 토큰 51,600개. 비용: 51,600 / 1,000,000 x $1.50 = $0.0774.
  • 범위 지정 후: 추출 텍스트 7페이지 x 페이지당 800토큰 가정 = 입력 토큰 5,600개. 비용: 5,600 / 1,000,000 x $1.50 = $0.0084.
  • 절약액: 출력 토큰을 제외하면 이번 요청의 입력 비용이 약 89% 줄어듭니다. 실제 페이지 밀도에 맞춰 수치를 대입하세요.

직접 사용하는 통합 문서에서 범위 크기를 측정해 보세요. 너무 잘게 나눈 호출을 여러 번 보내면 적절한 범위 하나를 보내는 것보다 총비용이 커질 수 있습니다(@zg0820).

운영에 적용하기 전 확인할 사항

파일 업로드가 성공했다고 해서 파싱까지 제대로 됐다는 뜻은 아닙니다. 파이프라인별로 다음을 확인하세요.

  1. 파싱 결과를 검증하세요. 행 수, 시트 이름, 페이지 수 등을 다시 답하게 한 뒤 원본과 비교합니다.
  2. 선택자를 모두 지정하세요. sheetIndex, visibleCells 또는 페이지 범위, contentLayers를 빠짐없이 설정합니다.
  3. 질문에 맞는 레이어를 고르세요. 차트와 레이아웃에는 VISUAL 또는 PAGE_IMAGE, 감사에는 DATA와 FORMULAS, 검색에는 PAGE_TEXT가 적합합니다.
  4. 범위를 벗어난 요청은 스테이징에서 시험하세요. 잘못된 페이지나 범위에 대해 오류를 반환하는지, 범위를 자동 조정하는지, 아무것도 반환하지 않는지는 스키마에 정의돼 있지 않습니다.
  5. 업로드 한도를 지키세요. 60MB 파일은 50MB 제한을 넘으므로 실패합니다. 인라인 데이터가 20MB를 넘는다면 Cloud Storage URL을 사용하세요.
  6. 다음 순서로 마이그레이션하세요. Excel 분할기는 sheetIndex와 visibleCells로, 보고서 래스터화기는 PAGE_TEXT를 사용하는 페이지 범위 방식으로 옮깁니다. 레이아웃이 필요한 경우에만 PAGE_IMAGE를 사용하고, 파일 전체를 반환하던 도구는 범위를 지정한 함수 응답으로 전환합니다.

인용한 문서에서 아직 확인되지 않은 부분도 있습니다. 숨겨진 행, 병합 셀, 차트, 삽입 이미지, 암호로 보호된 파일, 매크로 사용 파일, 손상된 파일을 어떻게 처리하는지는 이번 슬라이싱 공지나 위에 링크한 Firebase 입력 요구사항 문서에 나와 있지 않습니다. 실제로 사용하는 템플릿에서 직접 검증해야 합니다.

FAQ

함수 응답에서도 콘텐츠 범위를 지정할 수 있나요?

가능합니다. 도구가 파일 URI와 함께 SpreadsheetMetadata 또는 DocumentMetadata를 반환하면 모델에는 발췌한 부분만 전달됩니다. 에이전트 기반 문서 처리에 잘 맞는 방식입니다.

어떤 API 버전에서 범위 지정을 지원하나요?

Discovery revision 20261116의 v1beta와 v1alpha에서 확인됐으며, 안정 버전인 v1에는 없습니다. 버전을 고정하고 운영에 투입할 모델에서 먼저 테스트하세요.

Gemini가 업로드한 파일을 볼 수 없다고 하는 이유는 무엇인가요?

위 표와 제한사항을 기준으로 MIME 타입, 파일 크기, 선택자를 확인하세요. 그런 다음 모델에 시트 이름이나 페이지 수를 다시 말하게 하면 파싱이 정상적으로 이뤄졌는지 확인할 수 있습니다.

관련 글: Office 파이프라인에 사용할 모델을 고르는 데 도움이 되는 Gemini 4 Carbon vs Hydrogen API 가이드도 참고하세요.