Claude Files API: 한 번 업로드하고 어디서나 참조하기 (GA 가이드)

Claude Files API를 사용하면 파일을 한 번 https://api.anthropic.com/v1/files에 업로드하고 file_id를 돌려받은 다음, 매번 콘텐츠를 다시 전송하는 대신 해당 ID를 모든 Messages 요청에서 참조할 수 있습니다. 2026년 8월 20일부로 Claude Platform에서 정식 출시(GA)되었습니다. 베타 헤더가 필요 없고, 조직당 1TB의 스토리지가 제공되며, 요청 한도는 베타보다 5배 높습니다. Anthropic은 production agents post에서 컴퓨터 사용, 브라우저 도구, Skills API의 GA와 함께 이 변경 사항을 발표했습니다.

이 가이드는 전체 수명 주기를 다룹니다. 업로드, 메시지에서 파일 참조, 생성된 출력 다운로드, 만료, 워크스페이스 보안 모델, 그리고 프로덕션에서 마주치게 될 한도까지. 여기의 모든 단계가 HTTP 호출이므로, 코딩 에이전트가 전체 흐름을 일회성 curl 명령 더미 대신 Apidog CLI 테스트 시나리오로 바꿀 수 있습니다.

Files API가 하는 일

Files API는 Claude API를 위한 한 번 생성하고 여러 번 사용하는(create-once, use-many-times) 스토리지 계층입니다. 특정한 비용 문제를 해결합니다. 앱이 동일한 40페이지 PDF에 대해 수백 건의 요청에서 질문을 던진다면, 매 요청마다 그 PDF를 다시 업로드하는 것은 대역폭을 낭비하고 클라이언트 코드를 복잡하게 만듭니다. Files API를 사용하면:

Claude Files API lifecycle: upload, reference by file_id, download, delete

업로드: Anthropic의 스토리지에 파일을 업로드하고 고유한 file_id를 받습니다
참조: Messages 요청에서 콘텐츠 블록을 통해 해당 ID를 참조합니다
다운로드: 스킬이나 코드 실행 도구가 생성한 파일(차트, 스프레드시트, 덱)을 다운로드합니다
관리: 목록 조회, 메타데이터 조회, 삭제 작업으로 모든 것을 관리합니다

엔드포인트 표면은 작습니다:

작업	엔드포인트
파일 업로드	`POST /v1/files`
파일 목록 조회	`GET /v1/files`
파일 메타데이터 조회	`GET /v1/files/{file_id}`
파일 콘텐츠 다운로드	`GET /v1/files/{file_id}/content`
파일 삭제	`DELETE /v1/files/{file_id}`

이 모든 것은 표준 x-api-key 및 anthropic-version: 2023-06-01 헤더로 작동합니다. Messages API 자체가 처음이라면, Claude Opus 5 API guide에서 인증과 요청 형태의 기본을 다룹니다.

GA에서 달라진 점

Files API는 헤더 뒤에 숨은 베타로 몇 달을 보냈습니다. 2026년 8월 20일 GA 릴리스는 프로덕션 계획에 중요한 네 가지를 바꿨습니다:

What changed when the Claude Files API went GA

베타 헤더 없음. Claude API에서 표준 헤더로 요청이 작동합니다.
5배 높아진 요청 한도. 파일 작업은 이제 분당 약 500건의 요청을 허용하며, 영업팀을 통해 더 높은 한도를 받을 수 있습니다.
조직당 1TB 스토리지, 파일당 500MB 상한.
더 넓어진 플랫폼 지원. Files API는 Claude API에서 직접, AWS의 Claude Platform(베타), 그리고 Hosted on Anthropic 배포를 사용하는 Microsoft Foundry에서 작동합니다. Amazon Bedrock이나 Google Cloud Vertex AI에서는 사용할 수 없고, 제로 데이터 보존(zero-data-retention) 계약에도 해당되지 않습니다. 엄격한 보존 정책을 쓰고 있다면 그에 맞게 계획하세요.

파일 업로드

업로드는 JSON이 아니라 multipart 폼 요청입니다:

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/report.pdf"

응답은 나중에 파일을 참조하는 데 필요한 모든 것을 제공합니다:

{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "report.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "created_at": "2026-08-24T00:00:00Z",
  "downloadable": false,
  "expires_at": null
}

두 필드에 주목할 필요가 있습니다. downloadable은 업로드하는 모든 항목에 대해 false입니다. Claude가 스킬이나 코드 실행을 통해 생성한 파일만 다시 내려받을 수 있습니다. 그리고 expires_at은 업로드 시점에 만료를 설정하지 않는 한 null입니다(이에 대한 자세한 내용은 아래에서).

아래쪽의 Apidog CLI 테스트에서 업로드 단계는 id를 변수로 저장하므로, 이후의 모든 요청은 하드코딩된 문자열 대신 {{claude_file_id}}를 참조합니다.

메시지에서 파일 참조하기

업로드한 후에는 파일에 따라 세 가지 콘텐츠 블록 유형 중 하나를 통해 Messages 요청에 파일을 넣을 수 있습니다:

파일 유형	MIME 유형	콘텐츠 블록
PDF, 일반 텍스트	`application/pdf`, `text/plain`	`document`
이미지	`image/jpeg`, `image/png`, `image/gif`, `image/webp`	`image`
데이터셋 및 기타 모든 것	다양함	`container_upload` (코드 실행 도구)

PDF 요약 요청은 다음과 같습니다:

curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Summarize this document."},
        {"type": "document", "source": {"type": "file", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"}}
      ]
    }]
  }'

document 블록은 선택적 title, context, citations 필드도 받으므로, 업로드한 파일에 대해 인용 출력을 활성화할 수 있습니다. 이미지의 경우 블록 유형을 동일한 source 형태의 image로 바꾸세요. 스프레드시트, 읽는 것이 아니라 분석하고 싶은 CSV, 또는 document 블록이 받지 않는 형식의 경우 container_upload를 사용해 파일을 code execution tool에 넘기세요.

형식 관련 참고 사항 하나: .docx와 .xlsx는 document 블록에서 직접 지원되지 않습니다. 이미지 파싱과 인용을 유지하려면 Word 파일을 PDF로 변환하거나, 일반 텍스트를 추출해 인라인으로 보내세요.

생성된 파일 다운로드

다운로드 엔드포인트는 입력이 아니라 출력을 위한 것입니다. Claude가 코드 실행으로 차트를 만들거나 스킬을 통해 스프레드시트를 생성하면, 응답에는 bash_code_execution_tool_result 블록 안에 file_id가 포함됩니다. 그 ID는 다운로드할 수 있습니다:

curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  --output chart.png

업로드한 파일을 다운로드하려고 하면 400이 반환됩니다. 이에 대한 재시도 로직을 짜기 전에 메타데이터의 downloadable 플래그를 확인하세요. 그러면 지원 티켓을 아낄 수 있습니다. 이 업로드-인, 생성-아웃 루프는 새로 GA된 Skills API 워크플로의 중추로, 스킬이 이 동일한 엔드포인트를 통해 내려받는 Office 문서를 생성합니다. Claude Skills 가이드에서 스킬이 무엇이고 어떻게 실행되는지 다룹니다.

만료와 파일 수명 주기

파일은 삭제할 때까지, 또는 업로드 시 설정한 만료 시점까지 유지됩니다:

업로드 시 expires_in_seconds를 폼 필드로 전달하세요. 유효 범위: 3,600(1시간) ~ 7,776,000(90일). 한 번 설정하면 나중에 변경할 수 없습니다.
expires_at이 지나면 콘텐츠 다운로드는 404를 반환하고, 해당 파일을 참조하는 모든 Messages 요청은 추론 전에 실패합니다.
메타데이터는 만료 후 최대 30일 동안 읽을 수 있으며, 만료된 파일도 그 기간 동안 목록 응답에 계속 나타납니다. 필터링할 때 expires_at을 현재 시각과 비교하세요.
파일을 삭제하면 즉시 제거되고 되돌릴 수 없습니다. 만료된 콘텐츠는 스토리지 할당량에서 해제되지만 안전 검토를 위해 잠시 보존될 수 있으므로, 만료는 수명 주기 도구이지 삭제 보장 제어가 아닙니다.

보안 모델: 파일은 워크스페이스 범위

이것이 전체 API에서 가장 날카로운 부분입니다. 업로드한 파일은 최종 사용자, 대화, 세션에 한정되지 않고 전체 워크스페이스에서 접근할 수 있습니다. 같은 워크스페이스의 모든 API 키는 그곳에 업로드된 모든 파일을 읽을 수 있으며, 키를 다른 곳에 할당하지 않는 한 모든 키는 조직의 Default Workspace를 공유합니다.

실용적인 규칙:

최종 사용자로부터 file_id 값을 절대 받지 마세요. 사용자가 제공한 ID는 앱의 한 사용자가 다른 사용자의 업로드를 읽을 수 있게 합니다. 파일 ID를 서버 측 참조로 취급하고 사용자-파일 매핑은 자체 데이터베이스에 보관하세요.
멀티테넌트를 만드시나요? 테넌트당 하나의 워크스페이스. 워크스페이스가 격리 경계입니다. 각 조직은 최대 100개의 워크스페이스를 받으며, Anthropic 계정 팀이 이를 늘릴 수 있습니다.

비용 귀속을 위해 테넌트별 API 키를 이미 추적하고 있다면(how to cut your Claude API bill에서 깊이 다루는 주제입니다), 동일한 워크스페이스 배치로 파일 격리를 공짜로 얻을 수 있습니다.

한도와 청구

기준으로 삼아야 할 숫자:

한도	값
최대 파일 크기	500 MB
조직 스토리지	1 TB
File API 요청 한도	분당 약 500건
파일 이름 길이	1~255자
만료 범위	1시간 ~ 90일

청구는 친절합니다. 파일 업로드, 다운로드, 목록 조회, 삭제는 모두 무료입니다. 파일 콘텐츠가 Messages 요청에 들어갈 때만 비용을 지불하며, 일반 입력 토큰으로 가격이 매겨집니다. 열 번의 요청에서 참조되는 100페이지 PDF는 동일한 입력 토큰 비용이 열 번 발생합니다. Files API는 토큰 지출이 아니라 대역폭과 클라이언트 복잡성을 절약해 줍니다. 토큰 쪽에서 절약하려면 파일 참조를 프롬프트 캐싱과 함께 사용하세요.

다음 오류에 주의하세요: 파일이 500MB를 초과할 때 413, 조직이 1TB 상한에 도달했을 때 400, 파일 유형이 콘텐츠 블록과 맞지 않을 때 400(예: document 블록에 이미지), 그리고 워크스페이스 밖의 ID에 대해 404.

Claude Code가 Apidog CLI로 Files API를 테스트하게 하기

Files API는 여러 단계의 상태 기반 흐름이므로 셸 히스토리가 아니라 회귀 테스트가 필요합니다. Claude Code 또는 어떤 코딩 에이전트든 Apidog CLI를 통해 그 테스트를 만들고 실행할 수 있습니다. 한 번 설정하세요:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

토큰은 Apidog의 Account Settings, API Access Token에서 가져옵니다. 그런 다음 에이전트에게 프롬프트 하나를 주세요:

Use Apidog CLI on project <id>. Add the Files API endpoints (upload, list,
metadata, download, delete) and POST /v1/messages, with x-api-key from
{{ANTHROPIC_API_KEY}} and the anthropic-version header. Build a test scenario:
upload with expires_in_seconds=3600 and assert expires_at is set, save the id
as claude_file_id, reference it in a Messages call and assert 200, delete it,
then assert the metadata call returns 404. Run it and summarize any failures.

실행하는 명령은 Apidog CLI 2.2.7 기준으로 확인했습니다:

apidog cli-schema get endpoint-create
apidog endpoint create --project <id> --file files-upload.json
apidog test-scenario create --project <id> --name "Files API lifecycle" --priority 1
apidog test-scenario import-steps <scenarioId> --project <id> --source endpoint \
  --ids <uploadId>,<messagesId>,<deleteId>,<metadataId> --sync manual
apidog cli-schema validate test-scenario-update --file lifecycle.json
apidog test-scenario update <scenarioId> --project <id> --file lifecycle.json
apidog run -t <scenarioId> --project <id> -e <envId> \
  --env-var "ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY" -r cli,json

에이전트는 각 엔드포인트에 대해 endpoint create를 반복한 다음, 실행하기 전에 변수 추출과 검증(assertion)을 시나리오에 작성합니다. 나중에 테스트 파일을 바꾸는 것은 모든 요청이 아니라 업로드 단계 하나만 바꾸면 됩니다. 업로드 응답의 목(mock)도 요청하세요(apidog mock create). 그러면 프론트엔드 팀이 백엔드 프록시가 존재하기 전에 JSON 형태를 얻습니다. -r junit을 붙인 동일한 apidog run 명령은 CI에 바로 들어갑니다. Apidog CLI in Claude Code 가이드에서 에이전트 설정을 처음부터 끝까지 다룹니다.

FAQ

아직도 베타 헤더가 필요한가요? 아니요. 2026년 8월 20일 GA 이후로 Files API는 Claude API에서 표준 x-api-key 및 anthropic-version 헤더로 작동합니다. SDK나 프록시가 여전히 예전 files 베타 헤더를 고정하고 있다면 업그레이드할 때 제거하세요.

파일 콘텐츠를 업데이트할 수 있나요? 아니요. 파일은 업로드 후 변경할 수 없습니다. 새 파일을 업로드하고, 참조를 새 ID로 돌리고, 이전 파일을 삭제하세요.

Files API가 Bedrock이나 Vertex AI에서 작동하나요? 아니요. Claude API, AWS의 Claude Platform(베타), 그리고 Hosted on Anthropic 배포가 있는 Microsoft Foundry에서 작동합니다. Bedrock과 Vertex에서는 여전히 인라인 base64 콘텐츠가 필요합니다.

Files API는 Skills API가 출력에 사용하는 것과 같은 것인가요? 예. 스킬과 코드 실행 도구는 생성한 문서를 같은 파일 저장소에 쓰고, GET /v1/files/{file_id}/content를 통해 다운로드합니다. 그 워크플로의 Skills API side of that workflow는 자동 테스트와 잘 어울립니다.

마무리

Files API의 GA는 동일한 문서를 모든 요청에 base64로 밀어 넣는 마지막 변명을 없애줍니다. 한 번 업로드하고, ID로 참조하고, 만료를 설정하고, 테넌트 파일을 별도 워크스페이스에 보관하세요. API 표면은 다섯 개의 엔드포인트이며, 그중 어느 것이든 몇 분 만에 테스트할 수 있습니다. 코딩 에이전트가 Apidog CLI로 흐름을 스크립트하게 하고, 변수를 통해 file_id를 연결하고, 사용자가 엣지 케이스를 발견하기 전에 전체 수명 주기를 CI에 넣으세요.