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

アップロードしたファイルのdownloadableはfalseです。スキルまたはコード実行ツールによって作成されたファイルのみダウンロードできます。ファイルのダウンロードを参照してください。

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

アップロード後、アップロードレスポンスの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)

ファイルの管理

ファイルの一覧表示

アップロードしたファイルの一覧を取得します。このエンドポイントはページネーションされています。各リクエストは最大limit件のファイル（デフォルトは20件、最大1,000件）を返し、レスポンスのnext_pageカーソルをpageパラメータとして渡すと次のページを取得できます。ファイルは新しい順に並べられます。List Files APIリファレンスを参照してください。SDKは最初のページを返し、自動ページネーションヘルパーを提供します。CLIの例では--max-itemsで合計件数を制限しています。

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を参照してください。

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

ストレージ制限

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

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

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

ファイルの有効期限

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

ファイルがexpires_atに達すると、次のようになります。

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

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

監査ログ

組織でCompliance APIが有効になっている場合、そのActivity Feedは、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リリースのみです。それ以前のリリースでは、betas引数がなくてもclient.beta.filesからヘッダーが送信されます。
2. ページネーションを更新します。 after_id/before_idのループをpage/next_pageカーソルに置き換えるか、ファイルの管理に示されているSDKの自動ページネーションヘルパーを使用します。
3. expires_atを読み取ります。 このフィールドはヘッダーなしの場合にのみ表示されます。nullはファイルに有効期限がないことを意味します（ファイルの有効期限を参照）。

SDKのbeta名前空間

Python SDK 1.2.0、TypeScript SDK 0.122.0、Go SDK 1.68.0、Java SDK 2.59.0、Ruby SDK 1.67.0、およびC# SDK 12.44.0以降、client.beta.filesはfiles-api-2025-04-14を送信しなくなり、Betaプレフィックス付きの型名でclient.filesと同じ形式を返します。Managed Agentsベータヘッダーでのscope_idフィルタリングなど、まだベータ段階のFiles機能のために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リクエストに制限されています。より高い制限をリクエストするには、営業担当にお問い合わせください。

次のステップ

Compatibility