Claude API Files API 사용법: 파일 업로드부터 메시지 재사용까지

Claude API의 Files API — 파일을 미리 업로드해두고 file_id(파일 고유 식별자, 업로드 응답에 담겨 오는 문자열)로 이후 요청에서 계속 재사용할 수 있게 해주는 기능 — 를 쓰면 같은 문서나 이미지를 메시지를 보낼 때마다 다시 첨부하지 않아도 됩니다. Files API는 한때 베타 기능이었지만 지금은 별도의 베타 표시 없이 정식 기능으로 제공됩니다. 이 글은 그 소식 자체보다는, 실제로 파일을 업로드하고 메시지 요청에서 불러다 쓰는 절차에 집중해서 정리합니다.

Files API로 무엇을 할 수 있나요?

Files API는 파일을 한 번 업로드해두면 이후 여러 메시지 요청에서 file_id만으로 반복 참조할 수 있게 해주는 기능입니다. 크게 네 가지 작업을 지원합니다. 첫째, 파일을 업로드해 고유한 file_id를 받습니다. 둘째, Messages API(대화 요청을 보내는 API) 요청에서 그 file_id를 참조해 내용을 다시 보내지 않고도 사용합니다. 셋째, 코드 실행 도구나 스킬(skills)이 만들어낸 파일을 다운로드합니다. 넷째, 업로드한 파일 목록을 조회하거나 삭제하는 등 관리 작업을 합니다.

주의: 업로드한 파일은 특정 사용자나 대화가 아니라 워크스페이스 전체에서 접근할 수 있습니다. 같은 워크스페이스의 어떤 API 키로도 그 파일을 참조할 수 있다는 뜻입니다. 따라서 file_id를 최종 사용자에게 그대로 노출하거나, 사용자가 보낸 file_id를 그대로 신뢰해 사용하면 안 됩니다. 한 사용자가 다른 사용자가 올린 파일을 읽게 될 수 있습니다. file_id와 사용자 간의 연결은 서버 쪽에서 직접 관리하세요.

시작하기 전에 준비할 것

Files API를 쓰려면 몇 가지가 미리 준비되어 있어야 합니다.

• Claude API 키 — Claude 콘솔에서 발급받는 인증 값입니다. 터미널에서 ANTHROPIC_API_KEY 환경변수(터미널 세션에 저장해두는 값)로 설정해두면 매 요청마다 다시 입력하지 않아도 됩니다.
• anthropic-version 헤더 — API 요청마다 붙여야 하는 값으로, 아래 예시에서는 2023-06-01을 사용합니다.
• 요청을 보낼 도구 — 터미널에서 바로 시험해볼 때는 curl(명령줄에서 웹 요청을 보내는 도구), 실제 애플리케이션에 붙일 때는 Python·TypeScript 등 공식 SDK(소프트웨어 개발 키트 — 언어별로 API 호출을 편하게 감싸 놓은 라이브러리)를 씁니다.

1단계. 파일 업로드하기

파일 업로드는 POST https://api.anthropic.com/v1/files로 요청을 보내면 됩니다. curl로는 이렇게 씁니다.

FILE_ID=$(curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F "file=@/path/to/document.pdf" | jq -r '.id')
echo "$FILE_ID"

-F 옵션은 파일을 멀티파트 폼 데이터(multipart/form-data — 파일 같은 바이너리 데이터를 텍스트와 함께 보내는 표준 방식)로 첨부한다는 뜻입니다. 요청이 성공하면 아래와 같은 JSON 응답이 옵니다.

{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "document.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "created_at": "2025-01-01T00:00:00Z",
  "downloadable": false,
  "expires_at": null
}

이렇게 보이면 성공입니다: 응답에 file_로 시작하는 id 값이 담겨 있으면 업로드가 끝난 것입니다. 이 id가 앞으로 계속 쓸 file_id입니다. downloadable은 내가 직접 올린 파일에서는 항상 false이고(직접 올린 파일은 다시 다운로드할 수 없습니다), expires_at은 만료 시간을 따로 지정하지 않았다면 null로 남습니다.

2단계. 업로드한 파일을 메시지 요청에서 사용하기

업로드한 파일을 쓰려면 Messages API 요청의 content(대화 내용을 담는 배열) 안에 file_id를 참조하는 블록을 추가하면 됩니다. PDF나 텍스트 파일에는 document 블록을 씁니다.

{
  "model": "claude-opus-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "이 문서를 요약해줘." },
        {
          "type": "document",
          "source": { "type": "file", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w" }
        }
      ]
    }
  ]
}

이미지는 image 블록에 같은 방식으로 file_id를 넣습니다. 데이터셋 같은 파일을 코드 실행 도구(모델이 직접 파이썬·bash 코드를 실행해 데이터를 분석하게 하는 도구)에 넘길 때는 container_upload 블록에 file_id를 지정합니다. 세 경우 모두 파일 내용을 다시 보내는 게 아니라 file_id 하나만 보낸다는 점이 같습니다.

지원되는 파일 형식

Files API가 지원하는 파일 형식은 파일 종류에 따라 사용하는 콘텐츠 블록 타입이 다릅니다.

주의: .docx나 .xlsx처럼 위 표에 없는 형식은 document 블록으로 바로 쓸 수 없습니다. 이런 파일은 일반 텍스트나 PDF로 변환한 뒤 사용해야 합니다. 이미 텍스트 형태인 .csv·.md 파일은 내용을 그대로 메시지에 넣거나, text/plain 타입을 명시해 Files API로 업로드해도 됩니다. 이미지가 포함된 .docx 파일은 PDF로 변환하면 PDF 지원 기능(이미지 인식·인용 포함)을 그대로 활용할 수 있습니다.

파일 만료(expiration) 설정하기

파일이 자동으로 만료되게 하려면 업로드할 때 expires_in_seconds 값을 폼 필드로 함께 보내면 됩니다. 이 값은 3,600(1시간)에서 7,776,000(90일) 사이의 정수(초 단위)여야 합니다. 이 값을 지정하지 않으면 응답의 expires_at은 null로 남고, 자동으로 만료되지 않습니다.

파일이 expires_at 시점에 도달하면 다음과 같이 동작합니다.

• 파일 내용 다운로드(GET /v1/files/{file_id}/content) 요청은 404 오류를 반환합니다.
• 그 파일을 참조하는 Messages 요청은 모델 추론 전에 실패합니다.
• 파일 메타데이터(GET /v1/files/{file_id})는 만료 후 최대 30일까지는 여전히 조회할 수 있고, 목록 조회에도 계속 나타납니다. expires_at과 현재 시각을 비교해 만료된 파일을 걸러내면 됩니다.

주의: 만료 시간은 업로드할 때 한 번만 정할 수 있고, 이후에는 바꿀 수 없습니다. 예정보다 먼저 지우고 싶다면 만료를 기다리지 말고 DELETE /v1/files/{file_id}로 직접 삭제하세요. 삭제된 파일은 복구할 수 없습니다.

업로드한 파일 목록 조회·삭제·다운로드하기

업로드한 파일은 목록 조회, 메타데이터 조회, 삭제, (조건부) 다운로드로 관리합니다.

• 목록 조회 — GET /v1/files는 페이지 단위로 응답합니다(기본 20개, 최대 1,000개, 최신순). 응답의 next_page 커서를 다음 요청의 page 파라미터로 넘기면 다음 페이지를 받습니다. 특정 file_id들만 확인하고 싶다면 ids[] 쿼리 파라미터로 최대 100개까지 지정할 수 있는데, 이때는 page나 limit과 함께 쓸 수 없고 결과에 없는 파일 id는 조용히 생략됩니다.
• 메타데이터 조회 — GET /v1/files/{file_id}로 특정 파일의 정보만 확인합니다.
• 삭제 — DELETE /v1/files/{file_id}로 파일을 워크스페이스에서 제거합니다.
• 다운로드 — GET /v1/files/{file_id}/content로 받습니다. 단, 내가 직접 업로드한 파일은 다운로드할 수 없습니다. 다운로드가 가능한 파일은 스킬이나 코드 실행 도구가 만들어낸, 메타데이터의 downloadable이 true인 파일뿐입니다. 업로드한 파일을 다운로드하려 하면 400 오류가 돌아옵니다.

자주 발생하는 오류와 대처 방법

Files API를 쓰다 보면 아래와 같은 오류를 자주 만납니다. 원인을 알면 대부분 바로 해결됩니다.

저장 용량 한도와 요금

Files API는 파일 하나당 최대 500MB, 조직 전체로는 최대 1TB까지 저장할 수 있습니다. 업로드·다운로드·목록 조회·메타데이터 조회·삭제 같은 파일 관리 작업 자체는 무료입니다. 다만 메시지 요청에서 실제로 사용된 파일 내용은 입력 토큰(모델에 들어가는 텍스트·이미지 분량을 세는 단위)으로 과금됩니다. 파일 관련 API 호출은 분당 약 500회로 제한되며, 더 높은 한도가 필요하면 영업팀에 문의해야 합니다.

자주 묻는 질문

Q. 업로드한 파일을 나중에 다시 다운로드할 수 있나요?
아니요, 직접 업로드한 파일은 다운로드할 수 없습니다. 다운로드가 가능한 파일은 스킬이나 코드 실행 도구가 만들어낸, 메타데이터의 downloadable이 true인 파일뿐입니다. 업로드한 파일을 다운로드하려 하면 400 오류가 돌아옵니다.

Q. 만료 시간을 지정하지 않으면 파일이 얼마나 보관되나요?
expires_in_seconds를 지정하지 않으면 expires_at은 null로 남아 자동으로 만료되지 않고, 직접 DELETE 요청으로 삭제하기 전까지 보관됩니다.

Q. .docx나 .xlsx 파일도 Files API로 바로 쓸 수 있나요?
아니요, document 블록이 지원하는 형식은 PDF와 일반 텍스트뿐입니다. .docx·.xlsx는 텍스트나 PDF로 변환한 뒤 사용해야 합니다.

Q. 파일 업로드나 다운로드도 토큰처럼 과금되나요?
아니요, 업로드·다운로드·목록 조회·삭제 같은 파일 관리 작업 자체는 무료입니다. 다만 메시지 요청에서 실제로 사용된 파일 내용은 입력 토큰으로 과금됩니다.

업로드-참조-관리라는 흐름만 익히면, 같은 문서나 이미지를 반복해서 보내는 대신 file_id 하나로 깔끔하게 재사용할 수 있습니다. 만료 설정과 워크스페이스 접근 범위만 주의해서 다루면 됩니다.

관련 글

• Claude 프롬프트 작성법: 공식 문서 기반 핵심 원칙 6가지
• Claude 코워크(Cowork)란? — 파일을 직접 다루는 AI 작업 모드
• Claude 디자인(Design)이란? — 채팅으로 만드는 AI 디자인 도구
• Claude 메모리 기능 — 과거 대화를 기억하게 하고 관리하는 법
• Claude 스타일(Styles) — 말투·형식·길이를 내 방식으로 고정하기