Files API

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

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

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

Files APIの仕組み

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

• Anthropicの安全なストレージにファイルをアップロードし、一意のfile_idを受け取ります
• スキルやコード実行ツールによって作成されたファイルをダウンロードします
• コンテンツを再アップロードする代わりに、file_idを使用してMessagesAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。リクエストでファイルを参照します
• 一覧表示、取得、削除の操作でファイルを管理します

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,
  "expires_at": null
}

アップロードしたファイルのdownloadableAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。はfalseです。ダウンロードできるのは、スキルまたはコード実行ツールによって作成されたファイルのみです。ファイルのダウンロードを参照してください。

APIリファレンスには、ファイルオブジェクトのすべてのフィールドが記載されています。

メッセージでのファイルの使用

アップロード後、アップロードレスポンスのidをfile_idとして渡すことでファイルを参照します：

response = client.messages.create(
    model="claude-opus-5-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-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)

ファイルの管理

ファイルの一覧表示

アップロードしたファイルの一覧を取得します。このエンドポイントはページネーションされています。各リクエストは最大limitAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。件のファイル（デフォルトは20件、最大1,000件）を返し、レスポンスのnext_pageAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。カーソルをpageAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。パラメータとして渡すと次のページを取得できます。ファイルは新しい順に並べられます。ファイルの一覧APIリファレンスAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。を参照してください。SDKは最初のページを返し、自動ページネーションヘルパーを提供します。

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

ページングの代わりに、既知のファイルのセットを1回のリクエストで確認するには、最大100個のファイルIDをids[]クエリパラメータとして渡します。ids[]リクエストは常に単一のページを返し（next_pageはnull）、ワークスペース内のファイルに解決されないIDはdataから通知なしに除外されます。欠落を検出するには、返されたIDとリクエストしたIDを比較してください。ids[]はpageまたはlimitと組み合わせることはできません。

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

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

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

Claude APIでは、スキルによって作成されたファイルを含め、Claudeがコード実行ツールで生成したサポート対象の画像、動画、音声ファイルには、ダウンロード時に署名付きのC2PA Content Credentialsが付与されます。クレデンシャルの内容と検証方法については、生成されたファイルのContent Credentialsを参照してください。

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

ストレージ制限

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

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

• ファイルは、アップロードされたワークスペースにスコープされます。同じワークスペース内のどのリクエストからも参照できます。信頼できないソースからファイルIDを受け入れないでください（ワークスペースアクセスに関する警告を参照）。
• ファイルはアップロード後に変更したり名前を変更したりすることはできません。ファイルの内容を変更するには、新しいファイルをアップロードして古いファイルを削除してください。
• ファイルは、DELETE /v1/files/{file_id}エンドポイントで削除するか、expires_atに達するまで保持されます。
• 削除されたファイルは復元できません。
• ファイルは削除後まもなくAPI経由でアクセスできなくなりますが、アクティブなMessages API呼び出しおよび関連するツール使用では保持される場合があります。
• ユーザーが削除したファイルは、Anthropicのデータ保持ポリシーに従って削除されます。

ファイルの有効期限

ファイルを自動的に期限切れにするには、アップロード時にexpires_in_secondsAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。フォームフィールドを含めます。値は3,600（1時間）から7,776,000（90日）までの整数の秒数です。結果として得られるexpires_atAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。タイムスタンプ（RFC 3339）はすべてのファイルレスポンスに表示され、有効期限なしでアップロードされたファイルではnullになります。有効期限はアップロード時に一度だけ設定され、変更することはできません。

ファイルがexpires_atに達すると：

• そのコンテンツのダウンロード（GET /v1/files/{file_id}/content）は404エラーを返します。
• そのファイルを参照するMessagesリクエストは、推論の前に失敗します。
• そのメタデータ（GET /v1/files/{file_id}）は、expires_atが過去の日時となった状態で最大30日間読み取り可能なままです。
• その期間中は一覧レスポンスにも引き続き表示されます。期限切れのファイルを除外するには、expires_atを現在時刻と比較してください。

期限切れのファイルをDELETE /v1/files/{file_id}で削除すると、30日間の期間が経過するのを待たずに、そのメタデータが即座に削除されます。

監査ログ

組織でCompliance APIが有効になっている場合、そのアクティビティフィードには、Claude APIキーを使用して、またはClaude Consoleから行われたFiles API操作が記録されます。各アップロード（POST /v1/files）、コンテンツのダウンロード（GET /v1/files/{file_id}/content）、および削除（DELETE /v1/files/{file_id}）は、それぞれplatform_file_uploaded、platform_file_content_downloaded、またはplatform_file_deletedアクティビティとして表示されます。ファイルの一覧表示とファイルメタデータの取得は記録されません。Compliance APIが無効になっている間に発生した操作は記録されず、後から復元することもできないため、この監査証跡に依存する前にCompliance APIをセットアップしてください。Claude Platform on AWSでは、代わりにAWS CloudTrailデータイベントでファイル操作を監査してください。

files-api-2025-04-14からの移行

Files APIはベータを終了しており、ベータヘッダーは不要です。files-api-2025-04-14からの移行は任意です。このヘッダーを送信するリクエストは動作し続け、ベータのレスポンス形式を返し続けるため、既存のインテグレーションは変更するまで動作し続けます。ヘッダーを削除すると、それらのリクエストはこのページに記載されている形式に切り替わります。

移行するには：

1. ベータヘッダーを削除します。 リクエストからanthropic-beta: files-api-2025-04-14を削除します。SDKでは、client.beta.filesの代わりにclient.filesを呼び出します。client.beta.filesをそのまま使い続けられるのは、ヘッダーを送信しなくなったSDKリリースのみです。それより前のリリースでは、ベータ名を渡さなくてもclient.beta.filesからヘッダーが送信されます。
2. ページネーションを更新します。 after_id/before_idのループをpage/next_pageカーソルに置き換えるか、ファイルの管理に示されているSDKの自動ページネーションヘルパーを使用します。
3. expires_atを読み取ります。 このフィールドはヘッダーなしの場合にのみ表示されます。nullはファイルに有効期限がないことを意味します（ファイルの有効期限を参照）。

SDKのベータ名前空間

Python SDK 1.2.0、TypeScript SDK 0.122.0、Go SDK 1.68.0、Java SDK 2.59.0、PHP SDK 0.45.0、Ruby SDK 1.67.0、C# SDK 12.44.0以降では、client.beta.filesはfiles-api-2025-04-14を送信しなくなり、client.filesと同じ形式を、Betaプレフィックス付きの型名（PHPではAnthropic\Beta名前空間のクラス）で返します。ベータ段階にあるFiles機能、たとえばManaged Agentsベータヘッダー下でのscope_idによるフィルタリングなどについては、betasを通じてベータ名を受け付けます。それより前のSDKリリースはベータ版の形式に型付けされています。それらの型に依存している場合は、移行するまで以前のリリースを使い続けてください。

files-api-2025-04-14なしでanthropic-beta: managed-agents-2026-04-01を含むリクエストは、GET /v1/filesにおける1つの互換性措置を除き、このページの形式を受け取ります。before_idとafter_idは引き続き受け付けられ（pageまたはids[]とは組み合わせ不可）、一覧レスポンスにはnext_pageに加えてhas_more、first_id、last_idが含まれます。それ以降のManaged Agentsベータバージョンは通常の形式を受け取ります。

エラー処理

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

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

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

使用量と請求

Files APIの操作は無料です：

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

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

レート制限

ファイル関連のAPI呼び出しは、1分あたり約500リクエストに制限されています。より高い制限をリクエストするには、営業チームにお問い合わせください。

次のステップ

利用可能状況

Files APIはすべてのモデルで利用可能です。

APIサポート