Claude API の Files API と Skills API が GA、ベータヘッダーが不要に

Claude API の Files API と Agent Skills / Skills API が一般提供 (GA) になりました。これまで必要だった files-api-2025-04-14 と skills-2025-10-02 のベータヘッダーは、GA の API を使うだけなら不要です。アップロード済みファイルを参照する Messages API リクエストや、container パラメータで Skills を読み込む Messages API リクエストも同様です。

ただし、今回の変更を「ヘッダーを 1 行消すだけ」と捉えると危険です。移行は任意ですが、ヘッダーを外したリクエストは GA のレスポンス形状と挙動へ切り替わります。 Files API なら一覧のページネーション、Skills API ならフィールド名やバージョン識別子、削除の意味まで変わります。

この記事では、Anthropic の 2026 年 8 月 19 日付リリースノートと、Files API / Skills API の移行ガイドをもとに、既存実装を止めずに移す順番を整理します。

1. 何が変わったのか

変わったのは「ベータ機能がそのまま安定版になった」というラベルだけではありません。ヘッダーなしのリクエストに対して、現在の仕様として整理されたレスポンスが返るようになりました。

GA 後もベータヘッダーは直ちに無効化されません。Anthropic は、ヘッダーを送り続けるリクエストは従来どおり動作し、従来のレスポンス形状を返すと明記しています。したがって、公開日に全システムを一斉更新する必要はありません。

Files API はアップロードしたデータを Messages API へ渡す入口であり、Skills API はエージェントが使う手順やリソースのライフサイクルを扱う入口です。Agent Skills をチームでどう配布し、更新するかは Agent Skills のチーム共有と運用 もあわせて参照してください。

2. 移行は任意だがヘッダーを外すと応答の形が変わる

今回の最重要ポイントは、移行期限ではなく互換モードの境界がヘッダーにあることです。同じエンドポイントに同じようなリクエストを送っても、ベータヘッダーの有無によって契約が変わります。

このため、リリースの単位は「ヘッダー削除」と「パーサー変更」を必ずセットにします。段階移行するなら、まずステージングや限定トラフィックでヘッダーなしの契約を検証し、メトリクスとエラーを確認してから本番を切り替えます。戻すときも両方をセットで戻します。

3. Files API の移行手順 3 ステップ

Files API の公式ガイドは、移行を次の 3 ステップにまとめています。機能追加を混ぜず、この順番で契約だけを移すと差分を追いやすくなります。

ステップ 1: ベータヘッダーを外す

HTTP リクエストから次の指定を削除します。

anthropic-beta: files-api-2025-04-14

SDK では原則として client.beta.files から client.files へ切り替えます。ただし、新しい SDK では client.beta.files 自体がこのヘッダーを送らなくなります。つまり、ソースコード上の名前だけを見ても実際にどちらの形が返るか判断できません。SDK のバージョンも一緒に記録してください。

古い SDK の client.beta.files は、betas 引数を渡さなくてもベータヘッダーを送ります。既存の型に依存しているなら、移行が終わるまで古いリリースに留まる選択肢も公式ガイドに示されています。

ステップ 2: ページネーションを更新する

after_id / before_id のループを、page / next_page のカーソルへ置き換えます。ヘッダーなしで before_id または after_id を送ると 400 エラーになります。

let page: string | undefined;
 
do {
  const result = await client.files.list({ page });
  for (const file of result.data) {
    consume(file);
  }
  page = result.next_page ?? undefined;
} while (page);

SDK が提供する自動ページネーションを使う方法もあります。自前ループが多いほど切り替え漏れが起きるため、API 境界の薄いラッパーへ集約してから移すのが安全です。

特定のファイルだけをまとめて引く場合は ids[] も使えます。指定できるのは最大 100 件で、page や limit とは併用できません。解決できない ID は data から黙って除かれ、next_page は常に null です。全件存在する前提なら、返却件数や ID の集合を呼び出し側で照合します。

ステップ 3: expires_at を読む

ヘッダーなしのファイルオブジェクトには expires_at が常に現れます。有効期限がないファイルは null です。ベータ形状はフィールドそのものを返さないため、「欠落」と「null」を同じ意味として扱っていたコードは整理できます。

有効期限を付ける場合は、アップロード時に expires_in_seconds を指定します。公式ページでは 3,600 秒から 7,776,000 秒の整数とされ、有効期限はアップロード時に一度だけ設定され、後から変更できません。期限切れ後はコンテンツのダウンロードが 404 になり、そのファイルを使う Messages リクエストは推論前に失敗します。

4. SDK の beta 名前空間の扱い

2026 年 8 月 27 日付のリリースノートで、各 SDK の beta 名前空間も GA 後の契約へ揃えられました。次のバージョン以降では client.beta.files と client.beta.skills が該当ベータヘッダーを送らず、client.files と client.skills と同じ形を返します。

beta 名前空間に残ればベータ形状を維持できる、とは限らなくなりました。上表より前の SDK は beta 形状に型付けされ、beta 名前空間からヘッダーを送ります。上表以降は名前に beta が残っていても、Files / Skills については GA 形状です。

新しい beta 名前空間が残る理由は、Files や Skills に今後も個別のベータ機能があり得るためです。betas 引数で別のベータ機能を指定できますが、それは今回 GA になったヘッダーとは分けて考えます。

型名には Beta 接頭辞が残ります。また Messages の beta 型では、コンテナ内の Skill 参照型が BetaSkill から BetaContainerSkill へ改名されました。BetaSkill は今後 Skill リソース自体を指します。SDK 更新で型エラーが出たら、単なる名前変更として無視せず、どちらのオブジェクトを表しているか確認してください。SDK の大きな更新を安全に分ける考え方は anthropic Python SDK v1.0 の移行ガイド にもまとめています。

5. Skills API の GA

Files API にはベータヘッダーを外すための移行手順があります。一方、Skills API については、現行の Skills ガイドから Migrate from skills-2025-10-02 に相当する移行節を確認できませんでした。そのため、ここではリリースノートで確認できる GA の変更と、現行ドキュメントに記載されたフィールドだけを扱います。旧仕様を推測して新旧の対応表にすることはしません。

2026 年 8 月 19 日付のリリースノートでは、Agent Skills と /v1/skills が GA になり、skills-2025-10-02 ヘッダーが不要になったと案内されています。container パラメータで Skills を読み込む Messages API リクエストも対象です。ヘッダーを送り続けるリクエストは、引き続き変更なく動作します。

現行の Skills ガイドで確認できる GA の形は次のとおりです。

既存実装が別のフィールド名やバージョン表現を使っている場合は、ヘッダーを外す前に、実際に利用する SDK バージョンの型定義と現行の API リファレンスを突き合わせてください。Skills 側の移行ガイドを確認できていないため、旧フィールドからの一律な置換手順はここでは示しません。

2026 年 8 月 27 日付のリリースノートでは、Python SDK 1.2.0 をはじめ前節の表に挙げたバージョン以降で、client.beta.skills が skills-2025-10-02 ヘッダーを送らず、client.skills と同じ形を返すと案内されています。あわせて client.beta.skills.delete() は Skill と全バージョンをまとめて削除するようになり、Messages の beta 型でコンテナの Skill 参照を表していた BetaSkill は BetaContainerSkill に改名されました。

SDK 更新後も client.beta.skills という呼び出し名は残るため、名前だけで互換モードだと判断しないでください。特に削除処理と BetaSkill を型名として参照しているコードは、SDK を更新する前に検索しておく必要があります。

Skills を外部ツールや社内システムと組み合わせる場合、API 境界と権限を整理する考え方は MCP サーバーの自作ガイド も参考になります。

FIXIT

GA なら、ヘッダーを今すぐ消したほうがいい？

Hinata

急がなくて大丈夫です。ヘッダーは互換モードのスイッチなので、先に新しい形を読めるようにしましょう。

FIXIT

同じエンドポイントなのに、返り方だけ変わるんだ。

Hinata

そうです。Files はページ送り、Skills は削除まで変わります。1 行の削除としてレビューしないことが大切です。

FIXIT

じゃあ、何を合図に切り替える？

Hinata

新旧のレスポンスをテストで固定し、ステージングでヘッダーなしを通せた時点です。戻す手順もセットなら安心です。

6. いつ移行するかの判断

期限が示された強制移行ではないため、判断軸は「GA だから早いほどよい」ではありません。既存コードがどの形に依存し、変更をどれだけ観測できるかで決めます。

すぐ移行しやすいのは、API 呼び出しが 1 か所に集約され、自動テストでレスポンスを固定できるシステムです。Files のページネーション、Skills の削除前確認、保存済みバージョン ID の移行を小さな差分として出せます。新規実装は、特別な互換要件がない限りヘッダーなしの GA 形状から始めるのが自然です。

一方、移行を分けたほうがよいのは、SDK 更新が他の破壊的変更を含む場合、レスポンス型を複数サービスで共有している場合、Skill の旧バージョン値を永続化している場合です。とくに SDK のバージョン境界をまたぐと、client.beta.* の同じコードが違うヘッダーを送るため、依存ロックファイルだけの更新でも挙動が変わります。

実務では次の順が安全です。

1. files-api-2025-04-14、skills-2025-10-02、client.beta.files、client.beta.skills をコードと設定から検索する
2. SDK の実バージョンと、共通 HTTP クライアントが付けるヘッダーを記録する
3. ベータ形状と GA 形状の fixture を用意し、パーサーとページネーションをテストする
4. Skill 削除に確認や権限制御があるか、旧バージョン値を保存していないか確認する
5. ステージングでヘッダーを外し、400、404、一覧件数、削除監査を確認する
6. 本番を段階的に切り替え、ロールバック時はヘッダーとパーサーを同時に戻す

ファイルの期限切れを導入するなら、GA 移行とは別の変更にします。アップロード時にしか設定できず、期限切れ後は Messages が推論前に失敗するためです。移行と保持期間変更を同時に行うと、レスポンス契約の不具合と期限切れを切り分けにくくなります。

7. まとめ

Files API と Skills API の GA により、2 つのベータヘッダーは不要になりました。しかし、ヘッダーを外すことは単なる掃除ではなく、GA のレスポンス契約へ切り替える操作です。移行は任意で、送り続ける既存リクエストはベータ形状のまま動きます。

Files API は、ヘッダー削除、page / next_page へのページネーション更新、expires_at の読み取りという 3 ステップで移します。Skills API はそれに加えて、フィールド名、バージョン ID、一覧順、削除の意味を確認します。新しい SDK では beta 名前空間も GA 形状を返すため、名前ではなく SDK バージョンと実際のヘッダーで判断してください。

まず検索で影響範囲を固定し、レスポンス fixture と削除の安全確認を用意してから、限定環境でヘッダーを外すのが堅実です。API や AI 開発ツールの更新を継続的に追う体制づくりに困っている場合は、AI 開発ツール導入支援をご覧ください。個別の構成についてはお問い合わせからご相談いただけます。

出典は Anthropic の Claude API リリースノート、Files API の移行ガイド、Skills API の移行ガイドです。