機能

Files API

Files APIを使用して、Claude APIで使用するファイルをアップロードおよび管理する方法について説明します。

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

Files APIは現在ベータ版です。Files APIの使用体験を共有するには、フィードバックフォームからご連絡ください。

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

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は、ファイルを扱うためのシンプルな「一度作成して何度でも使用する」アプローチを提供します：

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

Files APIの使い方

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

ファイルのアップロード

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

curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -F "file=@/path/to/document.pdf"

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

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

curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -H "content-type: application/json" \
  -d '{
    "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_011CNha8iCJcU1wXNR6q4V8w"
            }
          }
        ]
      }
    ]
  }'

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

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

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

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

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

# 例：テキストファイルを読み込んでプレーンテキストとして送信
# 注：特殊文字を含むファイルの場合、base64エンコーディングを検討してください
TEXT_CONTENT=$(cat document.txt | jq -Rs .)

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d @- <<EOF
{
  "model": "claude-opus-4-6",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Here's the document content:\n\n${TEXT_CONTENT}\n\nPlease summarize this document."
        }
      ]
    }
  ]
}
EOF

画像を含む.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"
  }
}

ファイルの管理

ファイルの一覧表示

アップロードしたファイルの一覧を取得します：

curl https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

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

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

curl https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

ファイルの削除

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

curl -X DELETE https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

ファイルのダウンロード

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

curl -X GET "https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  --output downloaded_file.txt

ダウンロードできるのは、スキルまたはコード実行ツールによって作成されたファイルのみです。アップロードしたファイルはダウンロードできません。

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

ストレージ制限

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

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

ファイルはAPIキーのワークスペースにスコープされます。他のAPIキーは、同じワークスペースに関連付けられた他のAPIキーによって作成されたファイルを使用できます
ファイルは削除するまで保持されます
削除されたファイルは復元できません
ファイルは削除後すぐにAPI経由でアクセスできなくなりますが、アクティブなMessages API呼び出しおよび関連するツール使用では保持される場合があります
ユーザーが削除したファイルは、当社のデータ保持ポリシーに従って削除されます。

エラーハンドリング

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

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

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

使用量と課金

File API操作は無料です：

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

Messagesリクエストで使用されるファイルコンテンツは入力トークンとして課金されます。ダウンロードできるのは、スキルまたはコード実行ツールによって作成されたファイルのみです。

レート制限

ベータ期間中：

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

Was this page helpful?

機能

Files API

Files APIを使用して、Claude APIで使用するファイルをアップロードおよび管理する方法について説明します。

Files APIは現在ベータ版です。Files APIの使用体験を共有するには、フィードバックフォームからご連絡ください。

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

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

Files APIの仕組み

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

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

Files APIの使い方

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

ファイルのアップロード

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

curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -F "file=@/path/to/document.pdf"

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

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

curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -H "content-type: application/json" \
  -d '{
    "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_011CNha8iCJcU1wXNR6q4V8w"
            }
          }
        ]
      }
    ]
  }'

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

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

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

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

# 例：テキストファイルを読み込んでプレーンテキストとして送信
# 注：特殊文字を含むファイルの場合、base64エンコーディングを検討してください
TEXT_CONTENT=$(cat document.txt | jq -Rs .)

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d @- <<EOF
{
  "model": "claude-opus-4-6",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Here's the document content:\n\n${TEXT_CONTENT}\n\nPlease summarize this document."
        }
      ]
    }
  ]
}
EOF

ドキュメントブロック

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

ファイルの管理

ファイルの一覧表示

アップロードしたファイルの一覧を取得します：

curl https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

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

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

curl https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

ファイルの削除

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

curl -X DELETE https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

ファイルのダウンロード

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

curl -X GET "https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  --output downloaded_file.txt

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

ストレージ制限

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

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

ファイルはAPIキーのワークスペースにスコープされます。他のAPIキーは、同じワークスペースに関連付けられた他のAPIキーによって作成されたファイルを使用できます
ファイルは削除するまで保持されます
削除されたファイルは復元できません
ファイルは削除後すぐにAPI経由でアクセスできなくなりますが、アクティブなMessages API呼び出しおよび関連するツール使用では保持される場合があります
ユーザーが削除したファイルは、当社のデータ保持ポリシーに従って削除されます。

エラーハンドリング

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

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

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

使用量と課金

File API操作は無料です：

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

レート制限

ベータ期間中：

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

Was this page helpful?