Files API

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



サポートされているモデル

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

Files APIは、Claude API、Claude Platform on AWS、およびMicrosoft Foundryで利用できます。Microsoft Foundryでは、Files APIにはHosted on Anthropicデプロイメントが必要です。現在、Amazon BedrockまたはGoogle Cloudでは利用できません。



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"),
)
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.beta.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,
                    },
                },
            ],
        }
    ],
    betas=["files-api-2025-04-14"],
)
print(response)



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

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



ドキュメントブロック

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.beta.files.retrieve_metadata(file_id)
print(file)



ファイルの削除

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

client.beta.files.delete(file_id)



ファイルのダウンロード

スキルまたはコード実行ツールによって作成されたファイルをダウンロードします。アップロードしたファイルはダウンロードできません。生成されたファイルのfile_idは、それを作成したMessagesレスポンスのbash_code_execution_tool_resultコンテンツブロックに表示されます：

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

file_content.write_to_file("downloaded_file.txt")



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



ストレージ制限

• 最大ファイルサイズ： ファイルあたり500 MB
• 合計ストレージ： 組織あたり500 GB



ファイルのライフサイクル

• ファイルは、アップロードしたAPIキーのワークスペースにスコープされます。同じワークスペース内の任意のAPIキーがそれらを参照できます
• ファイルはアップロード後に変更または名前変更できません。ファイルの内容を変更するには、新しいファイルをアップロードして古いファイルを削除してください
• ファイルは、DELETE /v1/files/{file_id}エンドポイントで削除するまで保持されます
• 削除されたファイルは復元できません
• ファイルは削除後まもなくAPI経由でアクセスできなくなりますが、アクティブなMessages API呼び出しおよび関連するツール使用では保持される場合があります
• ユーザーが削除したファイルは、Anthropicのデータ保持ポリシーに従って削除されます。すべての機能におけるZDRの適格性については、APIとデータ保持を参照してください



エラー処理

Files APIを使用する際の一般的なエラーには以下が含まれます：

• ファイルが見つからない（404）： 指定されたfile_idが存在しないか、アクセス権がありません
• 無効なファイルタイプ（400）： ファイルタイプがコンテンツブロックタイプと一致しません（例えば、ドキュメントブロックで画像ファイルを使用する場合）
• ダウンロード不可（400）： アップロードしたファイルは"downloadable": falseであり、ダウンロードできません。スキルまたはコード実行ツールによって作成されたファイルのみダウンロードできます
• コンテキストウィンドウサイズの超過（400）： ファイルがコンテキストウィンドウサイズより大きい（例えば、/v1/messagesリクエストで500 MBのプレーンテキストファイルを使用する場合）
• 無効なファイル名（400）： ファイル名が長さの要件（1〜255文字）を満たしていないか、禁止文字（<、>、:、"、|、?、*、\、/、またはUnicode文字0〜31）を含んでいます
• ファイルが大きすぎる（413）： ファイルが500 MBの制限を超えています
• ストレージ制限の超過（400）： 組織が500 GBのストレージ制限に達しています

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "File `file_011CNha8iCJcU1wXNR6q4V8w` not found."
  },
  "request_id": "req_011CQFYcrRp7mCHLDsAYT8Qt"
}



使用量と課金

Files APIの操作は無料です：

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

Messagesリクエストで使用されるファイルコンテンツは、入力トークンとして課金されます。



レート制限

ベータ期間中：

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



次のステップ