목차
Claude 가이드 - 이 글은 시리즈의 일부입니다.
이 글은 Claude API 공식 문서의 Files API 페이지를 정리한 글입니다. 원문: https://platform.claude.com/docs/en/build-with-claude/files 마지막 확인: 2026-06-10
1. 한 줄 요약 #
긴 PDF를 한 번 올려두면, 다음부터는 짧은 이름표 하나만 적어서 계속 불러 쓸 수 있습니다.
2. 무엇이고 왜 좋을까 #
도서관에 책을 맡겨두고, 필요할 때마다 청구번호 하나만 적어 빌려 보는 것과 같습니다.
Files API(파일 에이피아이, 파일 관리용 인터페이스)는 PDF나 이미지를 Anthropic 서버에 한 번 업로드해두고, 그다음부터는 짧은 file_id(파일 아이디, 파일을 가리키는 이름표) 하나로 계속 참조하는 기능입니다. 매번 같은 자료를 본문에 붙여 넣지 않아도 되니, 코드도 간결해지고 전송 시간도 줄어듭니다.
기억해두면 좋은 숫자 하나 — 파일 1개당 최대 500MB(메가바이트), 전체 저장 공간은 한 조직당 500GB(기가바이트) 입니다. 책 한 권짜리 PDF는 물론, 강의 자료 수백 개를 올려두고 써도 충분한 양이지요. 그리고 업로드·삭제·목록 조회 같은 파일 관리 동작 자체는 무료입니다. 비용은 실제로 그 파일을 질문에 사용할 때만 발생합니다.
3. 이런 상황에서 써요 #
상황 1: 학생 — 강의 자료를 학기 내내 붙들고 질문하기 #
한 학기 내내 같은 강의 PDF 50장을 펴놓고 공부합니다. “3장 내용 요약해줘”, “이 개념을 예시로 설명해줘”, “기말고사에 나올 만한 부분은?” — 매번 PDF를 통째로 첨부하기엔 번거롭지요. 강의 자료를 한 번만 업로드해두면, 학기 내내 짧은 이름표 하나로 계속 질문할 수 있습니다. PDF가 어디 있는지 매번 찾아 끌어다 붙이지 않아도 됩니다.
상황 2: 직장인 — 회사 매뉴얼 챗봇 만들기 #
회사 매뉴얼이 100페이지가 넘는데, 동료들이 매일 비슷한 걸 물어봅니다. “휴가 신청은 어떻게 하나요?”, “법인카드 사용 규정이 어떻게 되죠?” 매뉴얼을 한 번 업로드해두면, 그 이후 모든 질문에서 같은 이름표만 적어 호출하면 됩니다. 자료를 매번 다시 보내지 않아도 되고, 매뉴얼이 개정되면 그 한 파일만 새로 올리고 이름표를 교체하면 끝입니다.
상황 3: 일반인 — 책 한 권을 옆에 두고 천천히 음미하기 #
좋아하는 책 한 권을 PDF로 가지고 있습니다. “이 장의 핵심 메시지가 뭘까?”, “비슷한 주제를 다룬 다른 책이 있을까?”, “이 부분, 친구에게 한 문장으로 설명한다면?” — 책을 한 번만 올려두면 며칠, 몇 주에 걸쳐 자유롭게 대화할 수 있습니다. 마치 책 옆에 작은 책상을 놓고 천천히 함께 읽어가는 친구가 생긴 느낌이지요.
4. 가볍게 시작하기 #
💻 개발 경험이 있으신가요? 아래 코드는 Python(파이썬) 기준 가장 짧은 예시입니다. 비개발자라면 “이런 식으로 쓰는구나” 정도로 보고 넘어가셔도 좋습니다. 핵심은 “올리고 → 이름표 받고 → 그 이름표로 질문한다"는 두 단계입니다.
import anthropic
client = anthropic.Anthropic()
# 1단계: 파일을 한 번 올려서 이름표(file_id)를 받습니다
uploaded = client.beta.files.upload(
file=("manual.pdf", open("/path/to/manual.pdf", "rb"), "application/pdf"),
)
file_id = uploaded.id # ← 이 짧은 문자열이 앞으로 계속 쓸 이름표
# 2단계: 질문할 때마다 PDF 본문 대신 이 이름표만 넣어줍니다
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "이 매뉴얼의 휴가 규정을 알려주세요."},
{"type": "document", "source": {"type": "file", "file_id": file_id}},
],
}],
betas=["files-api-2025-04-14"], # ← 베타 기능이라 헤더 한 줄 필요
)
print(response.content[0].text)처음 한 번만 파일을 올려두면, 그다음부터는 file_id 한 줄만 가지고 다니면 됩니다. PDF 경로를 매번 찾아 붙이지 않아도 되고, 두 번째 질문, 세 번째 질문에서도 같은 이름표를 그대로 재사용할 수 있습니다. 베타 기능이므로 betas=["files-api-2025-04-14"] 한 줄은 꼭 함께 적어주세요.
5. 흔한 오해와 함정 #
⚠️ 함정 1: “올린 파일을 다시 내려받고 싶은데, 왜 안 되죠?” #
내가 직접 올린 파일은 다시 다운로드할 수 없습니다. 다운로드가 가능한 파일은 Claude가 코드 실행 도구나 스킬을 통해 새로 만들어낸 결과물(예: 차트 이미지, 분석 결과 파일)뿐입니다. 원본 자료는 본인의 컴퓨터에 잘 보관해두세요. 서버에 올린 건 “참조용 사본"이라고 생각하시면 마음이 편합니다.
⚠️ 함정 2: “이미지 파일을 document 블록에 넣었더니 오류가 나요” #
파일 종류와 콘텐츠 블록 종류는 짝이 맞아야 합니다. ❌ 이미지를 document 블록에 넣으면 안 되고, ✅ 이미지는 image 블록, PDF·텍스트는 document 블록에 넣어야 합니다. 헷갈리면 “사진이면 image, 글이 든 문서면 document"라고 기억해두세요. CSV·엑셀 같은 표 파일은 별도 — 그건 텍스트로 변환해서 본문에 직접 붙이는 게 일반적입니다.
⚠️ 함정 3: “파일을 지웠는데, 진행 중이던 대화에서 아직 보이는 것 같아요” #
삭제는 즉시 적용되지 않을 수 있습니다. 이미 진행 중인 호출이나 도구 사용에서는 그 파일이 잠시 더 살아 있을 수 있고, API에서는 곧 사라집니다. 그리고 한 번 지운 파일은 복구가 안 되니, 중요한 자료는 삭제 전에 다시 한번 확인해주세요. “지움 = 되돌리기 없음"입니다.
6. 한 단계 더 (관심 있는 분만) #
🎯 여기까지 오신 분 환영합니다. 이 섹션은 더 깊이 알고 싶은 분을 위한 보너스입니다. 본문만 읽으셔도 충분합니다.
파일을 여러 개 올리다 보면 “지금 내 저장소에 뭐가 있었더라?” 싶은 순간이 옵니다. 그럴 때는 목록 조회와 메타데이터(파일 자체가 아닌 파일에 대한 정보 — 이름·크기·만든 날짜 등) 조회를 함께 쓰면 편합니다.
# 내가 올린 파일 목록 보기
files = client.beta.files.list()
for f in files.data:
print(f.id, f.filename, f.size_bytes)
# 특정 파일의 상세 정보 보기
info = client.beta.files.retrieve_metadata(file_id)
print(info.filename, info.mime_type)
# 더 이상 안 쓰는 파일은 삭제 (복구 불가)
client.beta.files.delete(file_id)함께 알아두면 좋은 비교 표 하나입니다.
| 파일 종류 | MIME 타입 | 어떤 블록에 넣나요? |
|---|---|---|
| application/pdf | document | |
| 일반 텍스트 | text/plain | document |
| 이미지 | image/jpeg, image/png 등 | image |
| 데이터셋(CSV 등) | 다양 | container_upload (코드 실행 도구용) |
CSV나 엑셀처럼 표가 든 파일은 위 표의 마지막 줄처럼 코드 실행 도구와 함께 쓰거나, 본문 텍스트로 변환해 직접 붙여 넣는 방법을 더 자주 씁니다. 또 한 가지 — Files API는 현재 베타 단계라 분당 약 100건의 요청 제한이 있습니다. 개인이 공부용으로 쓰기엔 차고 넘치는 양이니 안심하셔도 됩니다.
7. 한 마디 #
처음엔 “업로드, 이름표, 블록 타입…” 단어들이 낯설게 느껴질 수 있습니다. 하지만 한 번만 직접 해보면 “아, 그냥 파일 한 번 맡겨두고 짧은 번호로 부르는 거구나” 하고 단순하게 보이실 거예요. 혹시 막히면 함정 1~3 중 하나일 가능성이 큽니다 — 다운로드가 안 되거나, 블록 타입이 안 맞거나, 삭제한 파일이 잠시 더 보이는 경우. 천천히 확인해보세요.
다음 글에서는 #28 — PDF 지원을 살펴봅니다. 오늘 배운 file_id를 그대로 활용해서, PDF 안의 글뿐 아니라 그림·표까지 어떻게 함께 이해시키는지 다뤄볼게요. 천천히, 한 걸음씩 함께 가요.
Claude API 공식 문서를 한국어로 풀어쓴 시리즈입니다. 원문 정확성이 가장 우선, 의역과 친근함은 그 위에서.
