Files API

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



지원되는 모델

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

Files API는 Claude API, AWS의 Claude Platform, Microsoft Foundry에서 사용할 수 있습니다. 현재 Amazon Bedrock 또는 Vertex AI에서는 사용할 수 없습니다.



Files API 작동 방식

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

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



Files API 사용 방법



파일 업로드

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

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

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



메시지에서 파일 사용

업로드한 후에는 file_id를 사용하여 파일을 참조합니다:



파일 유형 및 콘텐츠 블록

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



기타 파일 형식 작업

document 블록으로 지원되지 않는 파일 유형(.csv, .txt, .md, .docx, .xlsx)의 경우, 파일을 일반 텍스트로 변환하고 콘텐츠를 메시지에 직접 포함하세요:



Document 블록

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 블록

이미지의 경우 image 콘텐츠 블록을 사용하세요:

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



파일 관리



파일 목록 조회

업로드한 파일 목록을 검색합니다:



파일 메타데이터 가져오기

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



파일 삭제

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



파일 다운로드

스킬 또는 코드 실행 도구에서 생성된 파일을 다운로드합니다:



파일 스토리지 및 제한



스토리지 제한

• 최대 파일 크기: 파일당 500 MB
• 총 스토리지: 조직당 500 GB



파일 수명 주기

• 파일은 API 키의 워크스페이스로 범위가 지정됩니다. 동일한 워크스페이스에 연결된 다른 API 키로 생성된 파일을 다른 API 키에서 사용할 수 있습니다
• 파일은 삭제할 때까지 유지됩니다
• 삭제된 파일은 복구할 수 없습니다
• 삭제 직후 API를 통해 파일에 접근할 수 없지만, 활성 Messages API 호출 및 관련 도구 사용에서는 계속 유지될 수 있습니다
• 사용자가 삭제한 파일은 Anthropic의 데이터 보존 정책에 따라 삭제됩니다.



데이터 보존

Files API를 통해 업로드된 파일은 DELETE /v1/files/{file_id} 엔드포인트를 사용하여 명시적으로 삭제될 때까지 보존됩니다. 파일은 여러 API 요청에서 재사용할 수 있도록 저장됩니다.

모든 기능에 대한 ZDR 적격성은 API 및 데이터 보존을 참조하세요.



오류 처리

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

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

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "File not found: file_011CNha8iCJcU1wXNR6q4V8w"
  }
}



사용량 및 요금

File API 작업은 무료입니다:

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

Messages 요청에서 사용되는 파일 콘텐츠는 입력 토큰으로 요금이 청구됩니다. 스킬 또는 코드 실행 도구에서 생성된 파일만 다운로드할 수 있습니다.



속도 제한

베타 기간 동안:

• 파일 관련 API 호출은 분당 약 100개 요청으로 제한됩니다
• 사용 사례에 더 높은 제한이 필요한 경우 문의해 주세요