Files API

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

Files APIはベータ版です。フィードバックフォームを通じてFiles APIの使用経験を共有してください。

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

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

Messages リクエストで file_id を参照することは、指定されたファイルタイプをサポートするすべてのモデルでサポートされています。例えば、画像はすべてのClaude 3+モデルでサポートされており、PDFはすべてのClaude 3.5+モデルでサポートされており、その他のさまざまなファイルタイプはClaude Haiku 4.5およびすべてのClaude 3.7+モデルのコード実行ツールでサポートされています。

Files APIは現在、Amazon BedrockまたはGoogle Vertex AIではサポートされていません。

Files APIの仕組み

Files APIは、ファイルを操作するためのシンプルな「一度アップロード、何度も使用」アプローチを提供します：

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

Files APIの使用方法

Files APIを使用するには、ベータ機能ヘッダーを含める必要があります：anthropic-beta: files-api-2025-04-14。

ファイルのアップロード

将来のAPI呼び出しで参照するためにファイルをアップロードします：

ファイルをアップロードしたときのレスポンスには以下が含まれます：

Output

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

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

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

ファイルタイプ	MIMEタイプ	コンテンツブロックタイプ	ユースケース
PDF	`application/pdf`	`document`	テキスト分析、ドキュメント処理
プレーンテキスト	`text/plain`	`document`	テキスト分析、処理
画像	`image/jpeg`, `image/png`, `image/gif`, `image/webp`	`image`	画像分析、ビジュアルタスク
データセット、その他

その他のファイル形式の操作

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

画像を含む.docxファイルの場合、まずPDF形式に変換してから、PDFサポートを使用して組み込みの画像解析を活用してください。これにより、PDFドキュメントから引用を使用できます。

ドキュメントブロック

PDFとテキストファイルの場合、document コンテンツブロックを使用します：

{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
  },
  "title": "Document Title", // オプション
  "context": "Context about the document", // オプション
  "citations": { "enabled": true } // オプション、引用を有効にします
}

画像ブロック

画像の場合、image コンテンツブロックを使用します：

{
  "type": "image",
  "source": {
    "type": "file",
    "file_id": "file_011CPMxVD3fHLUhvTqtsQA5w"
  }
}

ファイルの管理

ファイルをリストする

アップロードされたファイルのリストを取得します：

ファイルメタデータを取得する

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

ファイルを削除する

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

ファイルのダウンロード

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

ダウンロードできるのは、スキルまたはコード実行ツール](/docs/ja/agents-and-tools/tool-use/code-execution-tool)によって作成されたファイルのみです。アップロードしたファイルはダウンロードできません。

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

ストレージ制限

最大ファイルサイズ： ファイルあたり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文字）を満たしていないか、禁止文字（<、>、:、"、|、?、*、\、/、またはユニコード文字0～31）を含んでいます
ファイルが大きすぎます（413）： ファイルが500 MBの制限を超えています
組織が500 GBのストレージ制限に達しています

Output

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

使用とビリング

File API操作は無料です：

ファイルのアップロード
ファイルのダウンロード
ファイルのリスト
ファイルメタデータの取得
ファイルの削除

Messages リクエストで使用されるファイルコンテンツは入力トークンとして価格設定されます。ダウンロードできるのは、スキルまたはコード実行ツール](/docs/ja/agents-and-tools/tool-use/code-execution-tool)によって作成されたファイルのみです。

レート制限

ベータ期間中：

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

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

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

# メッセージ内でプレーンテキストとして送信
response = client.messages.create(
    model="claude-opus-4-7",
    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)