Files API

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



ファイルタイプのサポート

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



Files APIの仕組み

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

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



Files APIの使用方法



ファイルのアップロード

今後の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は、さまざまなコンテンツブロックタイプに対応するさまざまなファイルタイプをサポートしています。



ドキュメントブロック

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



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



ストレージ制限

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



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

• ファイルは、アップロードしたAPIキーのワークスペースにスコープされます。同じワークスペース内のどのAPIキーでもそれらを参照できます。信頼できないソースからファイルIDを受け入れないでください（ワークスペースアクセスに関する警告を参照）
• アップロード後にファイルを変更したり名前を変更したりすることはできません。ファイルの内容を変更するには、新しいファイルをアップロードして古いファイルを削除してください
• ファイルは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リクエストに制限されています
• ユースケースでより高い制限が必要な場合は、お問い合わせください



次のステップ