参考数据：Files API 参考 — Python

Data: Files API reference — Python

v2.1.63

Python Files API reference including file upload, listing, deletion, and usage in messages

文件 API — Python

文件 API 用于上传文件，以便在 Messages API 请求中使用。通过内容块中的 file_id 引用文件，避免在多次 API 调用中重复上传。

Beta 版本： 在您的 API 调用中传递 betas=["files-api-2025-04-14"]（SDK 会自动设置所需的请求头）。

关键信息

最大文件大小：500 MB
总存储空间：每个组织 100 GB
文件将持久保存，直到被删除
文件操作（上传、列出、删除）是免费的；在消息中使用的内容将按输入 token 计费
在 Amazon Bedrock 或 Google Vertex AI 上不可用

上传文件

python

import anthropic

client = anthropic.Anthropic()

uploaded = client.beta.files.upload(
    file=("report.pdf", open("report.pdf", "rb"), "application/pdf"),
)
print(f"File ID: {uploaded.id}")
print(f"Size: {uploaded.size_bytes} bytes")

在消息中使用文件

PDF / 文本文档

python

response = client.beta.messages.create(
    model="{\{OPUS_ID}\}",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Summarize the key findings in this report."},
            {
                "type": "document",
                "source": {"type": "file", "file_id": uploaded.id},
                "title": "Q4 Report",           # 可选
                "citations": {"enabled": True}   # 可选，启用引用
            }
        ]
    }],
    betas=["files-api-2025-04-14"],
)
print(response.content[0].text)

图像

python

image_file = client.beta.files.upload(
    file=("photo.png", open("photo.png", "rb"), "image/png"),
)

response = client.beta.messages.create(
    model="{\{OPUS_ID}\}",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {
                "type": "image",
                "source": {"type": "file", "file_id": image_file.id}
            }
        ]
    }],
    betas=["files-api-2025-04-14"],
)

管理文件

列出文件

python

files = client.beta.files.list()
for f in files.data:
    print(f"{f.id}: {f.filename} ({f.size_bytes} bytes)")

获取文件元数据

python

file_info = client.beta.files.retrieve_metadata("file_011CNha8iCJcU1wXNR6q4V8w")
print(f"Filename: {file_info.filename}")
print(f"MIME type: {file_info.mime_type}")

删除文件

python

client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w")

下载文件

只有由代码执行工具或技能创建的文件可以下载（用户上传的文件不行）。

python

file_content = client.beta.files.download("file_011CNha8iCJcU1wXNR6q4V8w")
file_content.write_to_file("output.txt")

完整端到端示例

上传一次文档，然后提出多个相关问题：

python

import anthropic

client = anthropic.Anthropic()

# 1. 上传一次
uploaded = client.beta.files.upload(
    file=("contract.pdf", open("contract.pdf", "rb"), "application/pdf"),
)
print(f"Uploaded: {uploaded.id}")

# 2. 使用相同的 file_id 提出多个问题
questions = [
    "What are the key terms and conditions?",
    "What is the termination clause?",
    "Summarize the payment schedule.",
]

for question in questions:
    response = client.beta.messages.create(
        model="{\{OPUS_ID}\}",
        max_tokens=1024,
        messages=[{
            "role": "user",
            "content": [
                {"type": "text", "text": question},
                {
                    "type": "document",
                    "source": {"type": "file", "file_id": uploaded.id}
                }
            ]
        }],
        betas=["files-api-2025-04-14"],
    )
    print(f"\\nQ: {question}")
    print(f"A: {response.content[0].text[:200]}")

# 3. 完成后清理
client.beta.files.delete(uploaded.id)

英文原文 / English Original

Files API — Python

The Files API uploads files for use in Messages API requests. Reference files via file_id in content blocks, avoiding re-uploads across multiple API calls.

Beta: Pass betas=["files-api-2025-04-14"] in your API calls (the SDK sets the required header automatically).

Key Facts

Maximum file size: 500 MB
Total storage: 100 GB per organization
Files persist until deleted
File operations (upload, list, delete) are free; content used in messages is billed as input tokens
Not available on Amazon Bedrock or Google Vertex AI

Upload a File

python

import anthropic

client = anthropic.Anthropic()

uploaded = client.beta.files.upload(
    file=("report.pdf", open("report.pdf", "rb"), "application/pdf"),
)
print(f"File ID: {uploaded.id}")
print(f"Size: {uploaded.size_bytes} bytes")

Use a File in Messages

PDF / Text Document

python

response = client.beta.messages.create(
    model="{\{OPUS_ID}\}",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Summarize the key findings in this report."},
            {
                "type": "document",
                "source": {"type": "file", "file_id": uploaded.id},
                "title": "Q4 Report",           # optional
                "citations": {"enabled": True}   # optional, enables citations
            }
        ]
    }],
    betas=["files-api-2025-04-14"],
)
print(response.content[0].text)

Image

python

image_file = client.beta.files.upload(
    file=("photo.png", open("photo.png", "rb"), "image/png"),
)

response = client.beta.messages.create(
    model="{\{OPUS_ID}\}",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {
                "type": "image",
                "source": {"type": "file", "file_id": image_file.id}
            }
        ]
    }],
    betas=["files-api-2025-04-14"],
)

Manage Files

List Files

python

files = client.beta.files.list()
for f in files.data:
    print(f"{f.id}: {f.filename} ({f.size_bytes} bytes)")

Get File Metadata

python

file_info = client.beta.files.retrieve_metadata("file_011CNha8iCJcU1wXNR6q4V8w")
print(f"Filename: {file_info.filename}")
print(f"MIME type: {file_info.mime_type}")

Delete a File

python

client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w")

Download a File

Only files created by the code execution tool or skills can be downloaded (not user-uploaded files).

python

file_content = client.beta.files.download("file_011CNha8iCJcU1wXNR6q4V8w")
file_content.write_to_file("output.txt")

Full End-to-End Example

Upload a document once, ask multiple questions about it:

python

import anthropic

client = anthropic.Anthropic()

# 1. Upload once
uploaded = client.beta.files.upload(
    file=("contract.pdf", open("contract.pdf", "rb"), "application/pdf"),
)
print(f"Uploaded: {uploaded.id}")

# 2. Ask multiple questions using the same file_id
questions = [
    "What are the key terms and conditions?",
    "What is the termination clause?",
    "Summarize the payment schedule.",
]

for question in questions:
    response = client.beta.messages.create(
        model="{\{OPUS_ID}\}",
        max_tokens=1024,
        messages=[{
            "role": "user",
            "content": [
                {"type": "text", "text": question},
                {
                    "type": "document",
                    "source": {"type": "file", "file_id": uploaded.id}
                }
            ]
        }],
        betas=["files-api-2025-04-14"],
    )
    print(f"\\nQ: {question}")
    print(f"A: {response.content[0].text[:200]}")

# 3. Clean up when done
client.beta.files.delete(uploaded.id)

参考数据：Files API 参考 — Python ​

文件 API — Python ​

关键信息 ​

上传文件 ​

在消息中使用文件 ​

PDF / 文本文档 ​

图像 ​

管理文件 ​

列出文件 ​

获取文件元数据 ​

删除文件 ​

下载文件 ​

完整端到端示例 ​

Files API — Python ​

Key Facts ​

Upload a File ​

Use a File in Messages ​

PDF / Text Document ​

Image ​

Manage Files ​

List Files ​

Get File Metadata ​

Delete a File ​

Download a File ​

Full End-to-End Example ​

参考数据：Files API 参考 — Python

文件 API — Python

关键信息

上传文件

在消息中使用文件

PDF / 文本文档

图像

管理文件

列出文件

获取文件元数据

删除文件

下载文件

完整端到端示例

Files API — Python

Key Facts

Upload a File

Use a File in Messages

PDF / Text Document

Image

Manage Files

List Files

Get File Metadata

Delete a File

Download a File

Full End-to-End Example