Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Files API를 사용하면 요청마다 콘텐츠를 다시 업로드하지 않고도 Claude API에서 사용할 파일을 업로드하고 관리할 수 있습니다. 이는 특히 코드 실행 도구를 사용하여 입력(예: 데이터셋 및 문서)을 제공한 다음 출력(예: 차트)을 다운로드할 때 유용합니다. 이 가이드 외에도 API 레퍼런스를 직접 살펴볼 수 있습니다.
Messages 요청에서 file_id를 참조하는 것은 해당 파일 유형을 지원하는 모든 모델에서 지원됩니다. 이미지는 현재 모든 Claude 모델에서 지원됩니다. PDF 및 코드 실행 도구를 사용하는 기타 파일 유형의 모델 지원 여부는 링크된 페이지를 참조하세요.
Files API는 파일 작업을 위해 한 번 생성하고 여러 번 사용하는 방식을 제공합니다.
file_id를 받습니다file_id를 사용하여 Messages 요청에서 파일을 참조합니다향후 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
}업로드한 파일의 경우 downloadable은 false입니다. 스킬 또는 코드 실행 도구가 생성한 파일만 다운로드할 수 있습니다. 파일 다운로드를 참조하세요.
업로드한 후에는 업로드 응답의 id를 file_id로 전달하여 파일을 참조하세요.
response = client.messages.create(
model="claude-opus-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는 서로 다른 콘텐츠 블록 유형에 해당하는 다양한 파일 유형을 지원합니다.
| 파일 유형 | MIME 유형 | 콘텐츠 블록 유형 | 사용 사례 |
|---|---|---|---|
application/pdf | document | 텍스트 분석, 문서 처리 | |
| 일반 텍스트 | text/plain | document | 텍스트 분석, 처리 |
| 이미지 | image/jpeg, image/png, image/gif, image/webp | image | 이미지 분석, 시각적 작업 |
| 데이터셋, 기타 | 다양함 | container_upload | 데이터 분석, 시각화 생성 |
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",
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개)을 반환하며, before_id 및 after_id 매개변수로 인접 페이지를 가져옵니다. List Files API 레퍼런스를 참조하세요. SDK는 첫 번째 페이지를 반환하고 자동 페이지네이션 헬퍼를 제공합니다. CLI 예제는 --max-items로 총 개수를 제한합니다.
client = anthropic.Anthropic()
files = client.beta.files.list()
print(files)특정 파일에 대한 정보를 조회하세요.
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")DELETE /v1/files/{file_id} 엔드포인트로 삭제할 때까지 유지됩니다Files API 사용 시 발생하는 일반적인 오류는 다음과 같습니다.
file_id가 존재하지 않거나 접근 권한이 없습니다"downloadable": false이며 다운로드할 수 없습니다. 스킬 또는 코드 실행 도구가 생성한 파일만 다운로드할 수 있습니다/v1/messages 요청에서 500 MB 일반 텍스트 파일 사용)<, >, :, ", |, ?, *, \, / 또는 유니코드 문자 0-31)를 포함합니다{
"type": "error",
"error": {
"type": "not_found_error",
"message": "File `file_011CNha8iCJcU1wXNR6q4V8w` not found."
},
"request_id": "req_011CQFYcrRp7mCHLDsAYT8Qt"
}Files API 작업은 무료입니다.
Messages 요청에서 사용된 파일 콘텐츠는 입력 토큰으로 요금이 부과됩니다.
베타 기간 동안:
Claude로 PDF를 처리하세요. 문서에서 텍스트를 추출하고, 차트를 분석하고, 시각적 콘텐츠를 이해할 수 있습니다.
샌드박스 컨테이너에서 Python 및 bash 코드를 실행하여 데이터를 분석하고, 파일을 생성하고, 솔루션을 반복적으로 개선하세요.
시각적 입력을 처리 및 분석하고 이미지에서 텍스트와 코드를 생성하세요.
| Supported platforms |
|
|---|
Was this page helpful?