Anthropic, Files API 정식 GA — 최대 32GB 파일 영구 저장·재사용 지원

Files API란 무엇인가

Anthropic Files API는 PDF, 텍스트, 이미지, 코드 파일 등을 Anthropic 서버에 영구적으로 업로드해두고, 이후 API 호출 시 file_id만 참조해 재사용하는 기능이다. 기존 멀티파트 메시지 방식은 호출마다 원본 바이너리를 전송해야 했기 때문에 대형 파일의 경우 네트워크 비용과 첫 토큰 레이턴시가 누적됐다.

지원 스펙

• 파일당 최대 크기: 512 MB
• 계정 총 저장 한도: 32 GB
• 보존 기간: 업로드 후 30일 (API로 수동 삭제 가능)
• 지원 MIME 타입: application/pdf, text/*, image/png, image/jpeg, image/webp, image/gif
• 호환 모델: Claude Opus 4.7, Claude Sonnet 4.6, Claude Haiku 4.5 전 버전

개발자 워크플로 변화

import anthropic

client = anthropic.Anthropic()

# 1) 파일 최초 업로드 (1회만 실행)
with open("architecture_docs.pdf", "rb") as f:
    file_obj = client.beta.files.upload(
        file=("architecture_docs.pdf", f, "application/pdf"),
    )
file_id = file_obj.id  # 예: file_abc123

# 2) 이후 호출에서는 file_id만 참조
response = client.beta.messages.create(
    model="claude-opus-4-7-20260901",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {"type": "file", "file_id": file_id},
                },
                {"type": "text", "text": "이 문서의 핵심 아키텍처 결정 사항을 한국어로 요약해줘."},
            ],
        }
    ],
    betas=["files-api-2026-05-22"],
)

위처럼 한 번 업로드한 파일을 팀 내 여러 서비스가 동일한 file_id로 공유 참조할 수 있다. CI 파이프라인에서 빌드 아티팩트를 업로드해두고, 코드 리뷰 봇·테스트 생성 봇이 각각 참조하는 패턴이 대표적이다.

비용 절감 시나리오 예시

| 방식 | 10 MB PDF × 하루 200회 호출 | 월 전송량 | |---|---|---| | 기존 (매 호출 전송) | 2 GB/day | ~60 GB | | Files API (1회 업로드) | 10 MB/day | ~300 MB |

실제 인풋 토큰 비용은 모델별로 공식 페이지 참조. 단, 파일 저장 자체에는 별도 스토리지 요금이 부과되며 정확한 단가는 Anthropic 가격 페이지를 확인해야 한다.

한국 개발팀 적용 포인트

1. 레거시 문서 RAG 파이프라인 단순화 수백 건의 내부 기술 문서를 벡터 DB에 임베딩하지 않고, Files API에 원문 PDF를 올려두고 Claude에게 직접 질의하는 경량 RAG 패턴이 가능해진다. 특히 한국어 특수 용어가 포함된 사내 문서는 청크 분할 없이 전문 컨텍스트를 유지하는 것이 더 정확한 경우가 많다.

2. 크리에이터 도구 — 대본·에셋 재사용 유튜브 대본, 브랜드 가이드라인 PDF 등을 한 번 올려두고 편집본 생성·자막 변환·썸네일 문구 작성 등 다양한 작업에서 재활용할 수 있다.

3. 주의사항

• Files API는 현재 베타 헤더 betas=["files-api-2026-05-22"] 필수
• 파일은 계정 단위 공유이므로 멀티테넌트 서비스라면 파일 접근 권한 로직을 애플리케이션 레이어에서 직접 관리해야 함
• 30일 이후 자동 삭제되므로 장기 보존이 필요한 원본은 별도 스토리지(S3 등)에 이중 보관 권장