Files APIで日本語ファイル名・日本語メタデータは正しく扱えるか

Files APIのファイル名バリデーションが禁止する文字に、日本語の文字は含まれません。仕様上は「請求書_2026年8月.pdf」のようなファイル名もそのままアップロードできます。ただし2点、思い込みやすい落とし穴があります。Files APIが返す「メタデータ」に任意のキー・値タグは存在しないこと、そして引用にファイル名を出す経路として公式が定めているのはdocumentブロックのtitleフィールドであり、filenameをそのまま渡すだけではその経路を通らないことです。この2点を押さえておくと、実装で手戻りが起きにくくなります。

Files APIのファイル名バリデーションに日本語は引っかかるか

公式のエラーリファレンスは、ファイル名の不正(400 Invalid filename)が起きる条件を次の2つに限定しています。

• 長さが1〜255文字の範囲外
• 禁止文字(< > : " | ? * \ /、またはUnicodeの制御文字0〜31)を含む

このリストにひらがな・カタカナ・漢字は含まれません。禁止されているのは記号の一部と、目に見えない制御文字だけです。つまり公式のバリデーション仕様を素直に読む限り、日本語ファイル名だからという理由でアップロードが拒否されることはありません。

FILE_ID=$(curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F "file=@請求書_2026年8月.pdf" | jq -r '.id')
echo "$FILE_ID"

「日本語メタデータ」は存在するか — アップロード応答のフィールドを確認する

Files APIにアップロードすると、レスポンスはid type filename mime_type size_bytes created_at downloadable expires_atの8フィールドだけを返します。ファイルに任意のキー・値を追加するカスタムメタデータの仕組みは存在しません。

つまり「日本語メタデータを設定できるか」という問いは、実質的に「filenameフィールドに日本語を書けるか」という問いと同じです。部署名やプロジェクト名をタグ付けする目的でFiles APIを使おうとしても、その置き場所は用意されていません。用途・カテゴリー・担当者のような分類情報を管理したいなら、file_idと紐づけて自社側のデータベースで持つ必要があります。ファイルの容量上限やライフサイクルの詳細はClaude Files APIの容量上限とファイルライフサイクル、file_idの扱いに関するセキュリティ面はClaude Files APIのfile_idセキュリティリスクと対策で扱っています。

一覧取得(GET /v1/files)にも、ファイル名でフィルタリングする検索パラメーターは用意されていません。受け付けるのはページネーション用のpageとlimit、既知のfile_idを最大100件まとめて確認するids[]だけです。そのため「あの日本語ファイル名のファイルを探す」操作はAPI側では完結しません。全件を取得してクライアント側で絞り込むか、アップロード時点でfile_idと日本語ファイル名の対応表を自前で持っておく運用が前提になります。

アップロード時にContent-Typeを省略した場合、MIMEタイプは拡張子などから自動判定されます。ファイル名の本体部分(拡張子より前の部分)が日本語でも、拡張子自体は.pdfや.pngのようにASCIIで付けるのが通例のため、この自動判定が日本語ファイル名によって狂うことは基本的にありません。

アップロード時のファイル名は、Claudeの応答に自動反映される保証はない

ここが誤解されやすい点です。Files APIのfilenameは、アップロードしたファイルを人間側が識別するための管理用フィールドです。公式ドキュメントが明記しているのは、Claudeに文書名を認識させ引用(citations)に反映させるにはdocumentブロックのtitleフィールドを別途指定する、という経路だけです。filenameをそのままdocumentブロックに渡した場合にClaude側でどう扱われるかについて、公式は言及していません。

{
  "type": "document",
  "source": { "type": "file", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w" },
  "title": "2026年8月分請求書",
  "citations": { "enabled": true }
}

titleは引用のdocument_titleとしてそのまま返り、Claudeへのプロンプトの一部としても渡ります。ただし引用対象のテキストそのものにはならず、title自体の長さにも制限があります。長い説明を持たせたいなら、contextフィールドに文字列やJSONとして格納する方法が公式に案内されています。

日本語ファイル名でアップロードしても、titleを指定し忘れると、Claudeの応答上にファイル名の情報が出てくることは基本的にないと考えられます。管理側の識別名(filename)と、Claudeに見せる文書名(title)は別のレイヤーだと切り分けて考える必要があります。

マルチパートアップロードで文字化けが起きるとしたらどこか

Files APIのファイル名バリデーション自体は日本語を許容しますが、アップロードを実装する側で文字化けが起きる余地は残っています。curl -F "file=@パス"のような書き方では、ファイル名はローカルのファイルパスから自動的に取り出されます。それがmultipart/form-dataのContent-Dispositionヘッダーに載せて送信される仕組みです。この変換は使っているHTTPクライアントやシェルのロケール設定に依存する部分で、Files APIの仕様書には明記されていません。

確実性を求めるなら、ファイル名を暗黙の自動抽出に任せず、SDK側で明示的に文字列として渡す実装が安全です。Python SDKならupload(file=("請求書.pdf", open(path, "rb"), "application/pdf"))のようにタプルの先頭でファイル名を明示でき、TypeScript SDKのtoFile()ヘルパーも同様にファイル名を独立した引数として受け取ります。ローカルのファイルパス文字列に依存させない書き方が、環境差による文字化けを避ける最短ルートです。

これはmultipart/form-dataのContent-Dispositionヘッダーが、非ASCII文字を含むファイル名の扱いを歴史的に複数方式でサポートしてきたことに起因します。素のfilename="..."パラメーターはASCII前提で規定されています。日本語のような非ASCII文字を安全に載せるには、拡張構文(filename*=UTF-8''...)が必要になる場面があります。どちらの方式で送るかはHTTPクライアントの実装依存であり、Files APIの仕様書自体はこの層を規定していません。自分で組んだ実装がどちらの方式を使っているか分からない場合は、アップロード直後にretrieve_metadataでファイル名を確認する運用を挟むのが実務的な確実性を担保する方法です。

アップロード後に文字化けへ気づいたらどう直すか

Files APIにアップロードしたファイルは、内容もファイル名も後から変更できません。ファイル名が想定と違う形で保存されてしまった場合、修正する手段は削除して同じ内容を正しいファイル名で再アップロードすることだけです。

さらに厄介なのは、アップロードしたファイルはdownloadableが常にfalseになり、ダウンロードして中身を目視確認する経路が存在しないことです。ファイル名を確認する手段はGET /v1/files/{file_id}のメタデータ取得だけに限られます。この制約の詳細はFiles APIでダウンロードできない理由にまとめています。

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

アップロード直後にこのリクエストでfilenameフィールドを確認し、意図した日本語文字列がそのまま返ってくるかをその場で見る運用が、文字化けに気づかないまま運用を続けるリスクを一番小さくします。

Files APIの「メタデータ」は管理用の識別子であって、Claude向けの情報ではない

ここまでを並べると、Files APIの設計思想が見えてきます。filenameはファイルを人間や自社システムが識別するための管理ラベルで、任意のタグを持たせる仕組みでもなければ、Claudeが自動で読み取る情報でもありません。Claudeに文書の性質を伝えたいなら、そのための専用フィールド(title context)が別に用意されています。

この分離は、日本語ファイル名を使ううえではむしろ好都合です。管理用のファイル名は社内の命名規則に合わせて日本語のまま自由に付けられる一方、Claudeへ渡すtitleは英語・日本語のどちらでも、引用の見え方を考えて別途設計できます。両者を同じ文字列で兼用しようとすると、管理のしやすさとClaudeへの伝わりやすさのどちらかを犠牲にしがちです。

まとめ

Files APIのファイル名バリデーションは日本語文字を禁止していないため、日本語ファイル名は仕様上アップロードできます。ただし255文字制限の文字・バイトどちらの数え方かは公式に明記されていないため、長いファイル名では余裕を持たせるのが安全です。「メタデータ」と呼べるのはfilenameを含む8フィールドだけで、任意のカスタムタグは存在せず、ファイル名での検索・フィルタリングもできません。そして引用に文書名を出す経路として公式が示しているのはdocumentブロックのtitleフィールドだけなので、Claudeに文書名を認識させたいならtitleを別途指定します。文字化けに気づいたら、修正はできないので削除と再アップロードで対応し、心配ならretrieve_metadataで都度確認しておきます。