Files API
Files API를 사용하면 각 요청마다 콘텐츠를 다시 업로드하지 않고도 Anthropic API에서 사용할 파일을 업로드하고 관리할 수 있습니다. 이는 코드 실행 도구를 사용하여 입력(예: 데이터셋 및 문서)을 제공한 다음 출력(예: 차트)을 다운로드할 때 특히 유용합니다. 또한 Files API를 사용하여 여러 API 호출에서 자주 사용되는 문서와 이미지를 계속 다시 업로드할 필요가 없게 할 수 있습니다.
Files API는 현재 베타 버전입니다. Files API 사용 경험을 공유하려면 피드백 양식을 통해 연락해 주세요.
지원되는 모델
Messages 요청에서 file_id
를 참조하는 것은 해당 파일 유형을 지원하는 모든 모델에서 지원됩니다. 예를 들어, 이미지는 모든 Claude 3+ 모델에서, PDF는 모든 Claude 3.5+ 모델에서, 그리고 코드 실행 도구를 위한 다양한 다른 파일 유형은 Claude 3.5 Haiku와 모든 Claude 3.7+ 모델에서 지원됩니다.
Files API는 현재 Amazon Bedrock 또는 Google Vertex AI에서 지원되지 않습니다.
Files API 작동 방식
Files API는 파일 작업을 위한 간단한 한 번 생성하고 여러 번 사용하는 접근 방식을 제공합니다:
- 파일을 안전한 스토리지에 업로드하고 고유한
file_id
를 받습니다 - 코드 실행 도구에서 생성된 파일을 다운로드합니다
- Messages 요청에서 콘텐츠를 다시 업로드하는 대신
file_id
를 사용하여 파일을 참조합니다 - 목록, 검색 및 삭제 작업으로 파일을 관리합니다
Files API 사용 방법
Files API를 사용하려면 베타 기능 헤더를 포함해야 합니다: anthropic-beta: files-api-2025-04-14
.
파일 업로드하기
향후 API 호출에서 참조할 파일을 업로드합니다:
파일 유형 및 콘텐츠 블록
Files API는 다양한 콘텐츠 블록 유형에 해당하는 다양한 파일 유형을 지원합니다:
파일 유형 | MIME 유형 | 콘텐츠 블록 유형 | 사용 사례 |
---|---|---|---|
application/pdf | document | 텍스트 분석, 문서 처리 | |
일반 텍스트 | text/plain | document | 텍스트 분석, 처리 |
이미지 | image/jpeg , image/png , image/gif , image/webp | image | 이미지 분석, 시각적 작업 |
데이터셋, 기타 | 다양함 | container_upload | 데이터 분석, 시각화 생성 |
문서 블록
PDF 및 텍스트 파일의 경우 document
콘텐츠 블록을 사용합니다:
이미지 블록
이미지의 경우 image
콘텐츠 블록을 사용합니다:
파일 관리하기
파일 목록 조회
업로드한 파일 목록을 검색합니다:
파일 메타데이터 가져오기
특정 파일에 대한 정보를 검색합니다:
파일 삭제하기
작업 공간에서 파일을 제거합니다:
파일 다운로드하기
코드 실행 도구에서 생성된 파일을 다운로드합니다:
코드 실행 도구에서 생성된 파일만 다운로드할 수 있습니다. 업로드한 파일은 다운로드할 수 없습니다.
파일 저장소 및 제한
저장소 제한
- 최대 파일 크기: 파일당 32 MB
- 총 저장 용량: 조직당 100 GB
파일 수명 주기
- 파일은 API 키의 작업 공간에 범위가 지정됩니다. 다른 API 키는 동일한 작업 공간과 연결된 다른 API 키에서 생성한 파일을 사용할 수 있습니다
- 파일은 삭제할 때까지 유지됩니다
- 삭제된 파일은 복구할 수 없습니다
- 삭제 직후 API를 통해 파일에 액세스할 수 없지만, 활성
Messages
API 호출 및 관련 도구 사용에서는 계속 유지될 수 있습니다
오류 처리
Files API 사용 시 일반적인 오류는 다음과 같습니다:
- 파일을 찾을 수 없음(404): 지정된
file_id
가 존재하지 않거나 액세스 권한이 없습니다 - 잘못된 파일 유형(400): 파일 유형이 콘텐츠 블록 유형과 일치하지 않습니다(예: 문서 블록에서 이미지 파일 사용)
- 파일이 너무 큼(413): 파일이 500 MB 제한을 초과합니다
- 저장소 제한 초과(403): 조직이 100 GB 저장소 제한에 도달했습니다
- 잘못된 파일 이름(400): 파일 이름이 길이 요구 사항(1-255자)을 충족하지 않거나 금지된 문자(
<
,>
,:
,"
,|
,?
,*
,\
,/
또는 유니코드 문자 0-31)를 포함합니다
사용 및 요금
File API 작업은 무료입니다:
- 파일 업로드
- 파일 다운로드
- 파일 목록 조회
- 파일 메타데이터 가져오기
- 파일 삭제
Messages
요청에서 사용된 파일 콘텐츠는 입력 토큰으로 가격이 책정됩니다. 코드 실행 도구에서 생성된 파일만 다운로드할 수 있습니다.
속도 제한
베타 기간 동안:
- 파일 관련 API 호출은 분당 약 100개 요청으로 제한됩니다
- 사용 사례에 더 높은 제한이 필요한 경우 문의하세요