Files API

Files APIを使用すると、リクエストごとにコンテンツを再アップロードすることなく、Claude APIで使用するファイルをアップロードおよび管理できます。これは、コード実行ツールを使用して入力（データセットやドキュメントなど）を提供し、出力（チャートなど）をダウンロードする場合に特に便利です。また、Files APIを使用することで、頻繁に使用するドキュメントや画像を複数のAPI呼び出しで繰り返し再アップロードする必要がなくなります。このガイドに加えて、APIリファレンスを直接確認することもできます。



対応モデル

Messagesリクエストでのfile_idの参照は、該当するファイルタイプをサポートするすべてのモデルで対応しています。画像は現在のすべてのClaudeモデルでサポートされています。PDFおよびコード実行ツールで使用するその他のファイルタイプについては、リンク先のページでモデルのサポート状況をご確認ください。

Files APIは、Claude API、Claude Platform on AWS、およびMicrosoft Foundryで利用できます。現在、Amazon BedrockおよびVertex AIでは利用できません。



Files APIの仕組み

Files APIは、ファイルを扱うための「一度作成して何度も使用する」シンプルなアプローチを提供します。

• ファイルをアップロードしてAnthropicの安全なストレージに保存し、一意のfile_idを受け取ります
• スキルまたはコード実行ツールから作成されたファイルをダウンロードします
• コンテンツを再アップロードする代わりに、file_idを使用してMessagesリクエストでファイルを参照します
• 一覧表示、取得、削除の操作でファイルを管理します



Files APIの使用方法



ファイルのアップロード

今後のAPI呼び出しで参照するファイルをアップロードします。

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

ファイルのアップロードに対するレスポンスには以下が含まれます。

{
  "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を使用してファイルを参照します。

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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,
                    },
                },
            ],
        }
    ],
    betas=["files-api-2025-04-14"],
)
print(response)



ファイルタイプとコンテンツブロック

Files APIは、さまざまなコンテンツブロックタイプに対応する各種ファイルタイプをサポートしています。



その他のファイル形式の扱い

documentブロックとしてサポートされていないファイルタイプ（.csv、.txt、.md、.docx、.xlsx）については、ファイルをプレーンテキストに変換し、コンテンツをメッセージに直接含めてください。

import pandas as pd
# ...
# 例：CSVファイルの読み込み
df = pd.read_csv("data.csv")
csv_content = df.to_string()

# メッセージ内でプレーンテキストとして送信
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": f"Here's the CSV data:\n\n{csv_content}\n\nPlease analyze this data.",
                }
            ],
        }
    ],
)

print(response.content[0].text)



ドキュメントブロック

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



ファイルの管理



ファイルの一覧表示

アップロードしたファイルの一覧を取得します。

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



ファイルメタデータの取得

特定のファイルに関する情報を取得します。

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



ファイルの削除

ワークスペースからファイルを削除します。

result = client.beta.files.delete(file_id)



ファイルのダウンロード

スキルまたはコード実行ツールによって作成されたファイルをダウンロードします。

file_content = client.beta.files.download(file_id)

# Save to file
file_content.write_to_file("downloaded_file.txt")



ファイルストレージと制限



ストレージ制限

• 最大ファイルサイズ： ファイルあたり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）： ファイルタイプがコンテンツブロックタイプと一致しません（例：ドキュメントブロックで画像ファイルを使用している）
• コンテキストウィンドウサイズを超過（400）： ファイルがコンテキストウィンドウサイズより大きいです（例：/v1/messagesリクエストで500 MBのプレーンテキストファイルを使用している）
• 無効なファイル名（400）： ファイル名が長さの要件（1〜255文字）を満たしていないか、禁止文字（<、>、:、"、|、?、*、\、/、またはUnicode文字0〜31）を含んでいます
• ファイルが大きすぎます（413）： ファイルが500 MBの制限を超えています
• ストレージ制限を超過（403）： 組織が500 GBのストレージ制限に達しています

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



使用量と課金

File APIの操作は無料です。

• ファイルのアップロード
• ファイルのダウンロード
• ファイルの一覧表示
• ファイルメタデータの取得
• ファイルの削除

Messagesリクエストで使用されるファイルコンテンツは、入力トークンとして課金されます。ダウンロードできるのは、スキルまたはコード実行ツールによって作成されたファイルのみです。



レート制限

ベータ期間中：

• ファイル関連のAPI呼び出しは、1分あたり約100リクエストに制限されています
• ユースケースでより高い制限が必要な場合は、お問い合わせください