Files API

Files API를 사용하면 요청마다 콘텐츠를 다시 업로드하지 않고도 Claude API와 함께 사용할 파일을 업로드하고 관리할 수 있습니다. 이는 코드 실행 도구를 사용하여 입력(예: 데이터셋 및 문서)을 제공한 다음 출력(예: 차트)을 다운로드할 때 특히 유용합니다. 이 가이드 외에도 API 레퍼런스를 직접 살펴볼 수 있습니다.

파일 유형 지원

Messages 요청에서 file_id를 참조하는 것은 해당 파일 유형을 지원하는 모든 모델에서 지원됩니다. 이미지는 현재 모든 Claude 모델에서 지원됩니다. PDF 및 코드 실행 도구와 함께 사용하는 기타 파일 유형의 경우, 모델 지원에 대해서는 링크된 페이지를 참조하세요.

Files API 작동 방식

Files API는 파일 작업을 위한 한 번 생성, 여러 번 사용 방식을 제공합니다:

• Anthropic의 보안 저장소에 파일을 업로드하고 고유한 file_id를 받습니다
• 스킬이나 코드 실행 도구가 생성한 파일을 다운로드합니다
• 콘텐츠를 다시 업로드하는 대신 file_id를 사용하여 Messages 요청에서 파일을 참조합니다
• 목록 조회, 검색, 삭제 작업으로 파일을 관리합니다

Files API 사용 방법

파일 업로드

향후 API 호출에서 참조할 파일을 업로드합니다:

uploaded = client.files.upload(
    file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)
file_id = uploaded.id
print(file_id)

파일 업로드에 대한 응답에는 다음이 포함됩니다:

{
  "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
}

downloadable은 업로드한 파일의 경우 false입니다. 스킬이나 코드 실행 도구가 생성한 파일만 다운로드할 수 있습니다. 파일 다운로드를 참조하세요.

메시지에서 파일 사용

업로드한 후에는 업로드 응답의 id를 file_id로 전달하여 파일을 참조합니다:

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Please summarize this document for me."},
                {
                    "type": "document",
                    "source": {
                        "type": "file",
                        "file_id": file_id,
                    },
                },
            ],
        }
    ],
)
print(response)

파일 유형 및 콘텐츠 블록

Files API는 서로 다른 콘텐츠 블록 유형에 해당하는 다양한 파일 유형을 지원합니다:

문서 블록

PDF 및 텍스트 파일의 경우 document 콘텐츠 블록을 사용합니다:

{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
  },
  "title": "Document Title", // Optional
  "context": "Context about the document", // Optional
  "citations": { "enabled": true } // Optional, enables citations
}

이미지 블록

이미지의 경우 image 콘텐츠 블록을 사용합니다:

{
  "type": "image",
  "source": {
    "type": "file",
    "file_id": "file_011CPMxVD3fHLUhvTqtsQA5w"
  }
}

컨테이너 업로드 블록

코드 실행 도구에 파일을 보내려면 container_upload 콘텐츠 블록을 사용합니다:

{
  "type": "container_upload",
  "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
}

기타 파일 형식 작업

document 블록이 지원하지 않는 파일 유형(예: .docx 및 .xlsx)의 경우, 파일을 일반 텍스트로 변환하고 콘텐츠를 메시지에 직접 포함하세요. .csv 및 .md 파일과 같이 이미 일반 텍스트인 파일은 이 방식으로 읽거나 명시적인 text/plain 콘텐츠 유형으로 Files API를 통해 업로드할 수 있습니다. 데이터셋을 텍스트로 읽는 대신 분석하려면, container_upload 블록을 사용하여 코드 실행 도구용으로 업로드하세요.

다음 예제는 텍스트 파일을 읽고 그 내용을 일반 텍스트로 전송합니다:

client = anthropic.Anthropic()

# 텍스트 파일을 읽습니다
with open("document.txt") as f:
    text_content = f.read()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": f"Here's the document content:\n\n{text_content}\n\nPlease summarize this document.",
                }
            ],
        }
    ],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

파일 관리

파일 목록 조회

업로드한 파일 목록을 검색합니다. 이 엔드포인트는 페이지네이션됩니다. 각 요청은 최대 limit개의 파일(기본값 20개, 최대 1,000개)을 반환하며, 응답의 next_page 커서를 page 매개변수로 다시 전달하면 다음 페이지를 가져옵니다. 파일은 최신순으로 정렬됩니다. List Files API 레퍼런스를 참조하세요. SDK는 첫 페이지를 반환하고 자동 페이지네이션 헬퍼를 제공합니다. CLI 예제는 --max-items로 총 개수를 제한합니다:

client = anthropic.Anthropic()
files = client.files.list()
print(files)

페이징 대신 알려진 파일 집합을 한 번의 요청으로 확인하려면, 최대 100개의 파일 ID를 ids[] 쿼리 매개변수로 전달하세요. ids[] 요청은 항상 단일 페이지를 반환하며(next_page는 null), 워크스페이스의 파일로 확인되지 않는 ID는 data에서 조용히 생략됩니다. 누락을 감지하려면 반환된 ID를 요청한 ID와 비교하세요. ids[]는 page 또는 limit와 결합할 수 없습니다.

파일 메타데이터 가져오기

특정 파일에 대한 정보를 검색합니다:

file = client.files.retrieve_metadata(file_id)
print(file)

파일 삭제

워크스페이스에서 파일을 제거합니다:

client.files.delete(file_id)

파일 다운로드

스킬이나 코드 실행 도구가 생성한 파일을 다운로드합니다. 업로드한 파일은 다운로드할 수 없습니다. 생성된 파일의 file_id는 해당 파일을 생성한 Messages 응답의 bash_code_execution_tool_result 콘텐츠 블록에 나타납니다:

file_content = client.files.download(file_id)

file_content.write_to_file("downloaded_file.txt")

Claude API에서는 스킬이 생성한 파일을 포함하여 Claude가 코드 실행 도구로 생성한 지원되는 이미지, 비디오 및 오디오 파일을 다운로드할 때 서명된 C2PA Content Credentials가 포함됩니다. 자격 증명에 포함되는 내용과 검증 방법은 생성된 파일의 Content Credentials를 참조하세요.

파일 저장 및 제한

저장 제한

• 최대 파일 크기: 파일당 500 MB
• 총 저장 용량: 조직당 1 TB

파일 수명 주기

• 파일은 업로드된 워크스페이스로 범위가 제한됩니다. 동일한 워크스페이스의 모든 요청이 이를 참조할 수 있습니다. 신뢰할 수 없는 소스로부터 파일 ID를 절대 받지 마세요(워크스페이스 접근 경고 참조)
• 파일은 업로드 후 수정하거나 이름을 변경할 수 없습니다. 파일의 콘텐츠를 변경하려면 새 파일을 업로드하고 이전 파일을 삭제하세요
• 파일은 DELETE /v1/files/{file_id} 엔드포인트로 삭제하거나 expires_at에 도달할 때까지 유지됩니다
• 삭제된 파일은 복구할 수 없습니다
• 파일은 삭제 직후 API를 통해 접근할 수 없게 되지만, 활성 Messages API 호출 및 관련 도구 사용에서는 유지될 수 있습니다
• 사용자가 삭제한 파일은 Anthropic의 데이터 보존 정책에 따라 삭제됩니다. 모든 기능에 대한 ZDR 적격성은 API 및 데이터 보존을 참조하세요

파일 만료

파일이 자동으로 만료되도록 하려면, 업로드할 때 expires_in_seconds 폼 필드를 포함하세요. 값은 3,600(1시간)에서 7,776,000(90일) 사이의 정수 초 단위입니다. 결과로 생성되는 expires_at 타임스탬프(RFC 3339)는 모든 파일 응답에 나타나며, 만료 없이 업로드된 파일의 경우 null입니다. 만료는 업로드 시 한 번 설정되며 변경할 수 없습니다.

파일이 expires_at에 도달하면:

• 콘텐츠 다운로드(GET /v1/files/{file_id}/content)는 404 오류를 반환합니다
• 해당 파일을 참조하는 Messages 요청은 추론 전에 실패합니다
• 메타데이터(GET /v1/files/{file_id})는 expires_at이 과거인 상태로 최대 30일 동안 읽을 수 있습니다
• 해당 기간 동안 목록 응답에 계속 나타납니다. 만료된 파일을 필터링하려면 expires_at을 현재 시간과 비교하세요

DELETE /v1/files/{file_id}로 만료된 파일을 삭제하면 30일 기간이 경과할 때까지 기다리지 않고 메타데이터가 즉시 제거됩니다.

감사 로깅

조직에 Compliance API가 활성화되어 있는 경우, 해당 Activity Feed는 Claude API 키로 또는 Claude Console에서 수행된 Files API 작업을 기록합니다. 각 업로드(POST /v1/files), 콘텐츠 다운로드(GET /v1/files/{file_id}/content), 삭제(DELETE /v1/files/{file_id})는 각각 platform_file_uploaded, platform_file_content_downloaded, platform_file_deleted 활동으로 나타납니다. 파일 목록 조회 및 파일 메타데이터 검색은 기록되지 않습니다. Compliance API가 꺼져 있는 동안 발생하는 작업은 기록되지 않으며 나중에 복구할 수 없으므로, 이 감사 추적에 의존하기 전에 Compliance API를 설정하세요. Claude Platform on AWS에서는 대신 AWS CloudTrail 데이터 이벤트로 파일 작업을 감사하세요.

files-api-2025-04-14에서 마이그레이션

Files API는 베타에서 벗어났으며 베타 헤더가 필요하지 않습니다. files-api-2025-04-14에서 마이그레이션하는 것은 선택 사항입니다. 여전히 이를 전송하는 요청은 계속 작동하고 베타 응답 형태를 계속 반환하므로, 기존 통합은 변경할 때까지 계속 작동합니다. 헤더를 제거하면 해당 요청이 이 페이지에 문서화된 형태로 전환됩니다:

마이그레이션하려면:

1. 베타 헤더를 제거하세요. 요청에서 anthropic-beta: files-api-2025-04-14를 삭제하세요. SDK에서는 client.beta.files 대신 client.files를 호출하세요. client.beta.files를 유지하는 것은 더 이상 헤더를 전송하지 않는 SDK 릴리스에서만 작동합니다. 이전 릴리스는 betas 인수가 없어도 client.beta.files에서 이를 전송합니다.
2. 페이지네이션을 업데이트하세요. after_id/before_id 루프를 page/next_page 커서로 교체하거나, 파일 관리에 표시된 SDK 자동 페이지네이션 헬퍼를 사용하세요.
3. expires_at을 읽으세요. 이 필드는 헤더 없이만 나타납니다. null은 파일에 만료가 없음을 의미합니다(파일 만료 참조).

SDK 베타 네임스페이스

Python SDK 1.2.0, TypeScript SDK 0.122.0, Go SDK 1.68.0, Java SDK 2.59.0, Ruby SDK 1.67.0, C# SDK 12.44.0부터 client.beta.files는 더 이상 files-api-2025-04-14를 전송하지 않으며 Beta 접두사가 붙은 유형 이름으로 client.files와 동일한 형태를 반환합니다. 이는 Managed Agents 베타 헤더 하의 scope_id 필터링과 같이 여전히 베타 상태인 Files 기능에 대해 betas 인수를 허용합니다. 이전 SDK 릴리스는 베타 형태로 타입이 지정되어 있습니다. 해당 유형에 의존하는 경우, 마이그레이션할 때까지 이전 릴리스를 유지하세요.

files-api-2025-04-14 없이 anthropic-beta: managed-agents-2026-04-01을 전달하는 요청은 GET /v1/files에 대한 하나의 호환성 편의 기능과 함께 이 페이지의 형태를 받습니다: before_id 및 after_id는 여전히 허용되며(page 또는 ids[]와 결합 불가), 목록 응답에는 next_page와 함께 has_more, first_id, last_id가 포함됩니다. 이후 Managed Agents 베타 버전은 일반 형태를 받습니다.

오류 처리

Files API 사용 시 일반적인 오류는 다음과 같습니다:

• 파일을 찾을 수 없음(404): 지정된 file_id가 존재하지 않거나 접근 권한이 없습니다
• 잘못된 파일 유형(400): 파일 유형이 콘텐츠 블록 유형과 일치하지 않습니다(예: 문서 블록에서 이미지 파일 사용)
• 다운로드 불가(400): 업로드한 파일은 "downloadable": false이며 다운로드할 수 없습니다. 스킬이나 코드 실행 도구가 생성한 파일만 다운로드할 수 있습니다
• 컨텍스트 윈도우 크기 초과(400): 파일이 컨텍스트 윈도우 크기보다 큽니다(예: /v1/messages 요청에서 500 MB 일반 텍스트 파일 사용)
• 잘못된 파일 이름(400): 파일 이름이 길이 요구 사항(1-255자)을 충족하지 않거나 금지된 문자(<, >, :, ", |, ?, *, \, /, 또는 유니코드 문자 0-31)를 포함합니다
• 파일이 너무 큼(413): 파일이 500 MB 제한을 초과합니다
• 저장 제한 초과(400): 조직이 1 TB 저장 제한에 도달했습니다

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "File `file_011CNha8iCJcU1wXNR6q4V8w` not found."
  },
  "request_id": "req_011CQFYcrRp7mCHLDsAYT8Qt"
}

사용량 및 청구

Files API 작업은 무료입니다:

• 파일 업로드
• 파일 다운로드
• 파일 목록 조회
• 파일 메타데이터 가져오기
• 파일 삭제

Messages 요청에서 사용되는 파일 콘텐츠는 입력 토큰으로 가격이 책정됩니다.

속도 제한

파일 관련 API 호출은 분당 약 500개의 요청으로 제한됩니다. 더 높은 제한을 요청하려면 영업팀에 문의하세요.

다음 단계

Compatibility