ファイルとアセット

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

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

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経由でアップロードされたファイルは、DELETE /v1/files/{file_id}エンドポイントを使用して明示的に削除されるまで保持されます。ファイルは複数のAPIリクエストにわたって再利用するために保存されます。

すべての機能にわたるZDRの適格性については、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は現在ベータ版です。Files APIのご利用体験を共有するには、フィードバックフォームからご連絡ください。

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

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

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

Files APIの仕組み

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

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

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呼び出しおよび関連するツール使用では引き続き存在する場合があります
ユーザーが削除したファイルは、データ保持ポリシーに従って削除されます。

データ保持

すべての機能にわたるZDRの適格性については、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?