API / SDK
開発者向けの Claude API / SDK 連携ガイドです。認証、ストリーミング、ツール呼び出し、コスト管理、エージェント構築まで、動くコード例とともに本番運用の勘所を解説します。個人開発での実運用の実例も交えて紹介しています。
定期タスクの冒頭で WS が空になった朝、シェルが二つあることを知りました
定期タスクの手順1で作業フォルダの変数が空になりました。原因はシェルが二つあることでした。両方で同じ検査を走らせた結果と、tool_result で取り違えを止める実装をお伝えします。
Make から Claude API に 40 行流すと 14 行目で止まる — 429 を待ち時間の計算で避ける
表計算の行を1件ずつ Claude API に渡すノーコード自動化が、途中で 429 になる理由と直し方です。模擬バケットで7通りの間隔を比べ、Sleep の秒数を 60÷上限−応答時間 で決める式と、失敗行を落とさない設定を示します。
retry-after が 120 秒の 429 を受けると、Anthropic SDK の自動リトライは 120 秒待とうとしました
Anthropic SDK の自動リトライを模擬サーバーで12通り確かめました。既定は2回まで、retry-after は上限なしで従い、上限到達の429は待っても通りません。待ち時間と総時間に上限を持つ呼び出し口のコードと実測ログを載せます。
Haiku 5.5 は単価が下がるのに、4.5 換算で約 7.7 万トークンを超えると請求が跳ねます
Haiku 4.5 から 5.5 へ移すと、価格表だけ見れば約 1/10 です。ただし同じ文章が約 30% 多いトークンになり、入力が 10 万を超えた時点で単価が 5 倍になります。境目を 4.5 換算で計算し、実際に動かした出力と、移行時に直す 400 の項目を並べました。
Sonnet 4.5 の退役前に、コードに残った「400 になる引数」を一本のスクリプトで拾いました
claude-sonnet-4-5 は 11 月 30 日に退役します。モデル ID を書き換えるだけでは、budget_tokens・prefill・tool_choice などで 400 が返ります。公式の移行ガイドの該当箇所を正規表現にしたスキャナと、実行結果、直し方の順番をまとめました。
モデルを切り替える前に、自分の呼び出しの形を候補モデルへ1トークンで再生する
モデルIDを書き換えて本番を回すと、400 は最初のリクエストで返ります。thinking の指定や tool_choice など自分の呼び出しの形を、max_tokens 16 の再生で先に確かめる小さな仕組みを書きました。
Claude が 529 を返した夜、頼みのフォールバック先まで落ちました — cache_control は境界で剥がす
Claude API のフォールバック先で TypeError が出た原因は、cache_control 付きの content block をそのまま他社モデルへ渡していたことでした。境界で剥がす関数と送る直前の検問、そして発火する前にフォールバック経路を試す運用を書き残します。
PDF の入力トークンは文字数では読めません — 送る前にページ数から上限で挟む
Claude API に PDF を送る前の入力トークンを、文字数ではなくページ数から上限で挟んで見積もる手順です。A4 9 ページの日本語文書で文字数見積もりの 6.6 倍になった実測と、解像度ティアとトークナイザの二重の増分、count_tokens が file_id を数えられない制約までをまとめます。
非推奨の通知が出た朝、設定を書き換える前にバージョンを確かめた話
Claude Desktop / Cowork の管理構成キーが 10 月 7 日に受付終了します。先に書き換えると壊れるもの、触らなくても意味が変わるものを仕分ける手順を書き残します。
画像は20枚ずつ送っています — 21枚目から全画像に別の上限がかかると知った日
素材フォルダの62枚を一度に送ったら invalid_request_error で落ちました。容量ではなく枚数が原因です。視覚トークンを28pxのパッチで数え直し、枚数・寸法・ペイロードの3つの上限を同時に見てバッチを組むまでの記録です。
コンソールで作ったエージェントは、ant apply では引き取れませんでした
ant apply はファイルからエージェントや環境を作り直します。拒んでくれる場面と、黙って二つ目を作る場面の境目、そして claude-lock.json をコミットする理由を手順つきで整理しました。
セッションの予算上限に「25」と書くと、25 セントで止まります
Managed Agents のセッション予算は補助単位の文字列で渡します。amount の単位を取り違えて budget_reached で止まった経緯と、停止を検知して上げ直す・外す手順を型定義の実測とともにまとめました。
キャッシュ読み取りが 75% 安くなっても、請求の下がり方は構成しだいで 10 倍違います
Fable 5.1 と Mythos 5.1 でキャッシュ読み取りの倍率が 0.1 から 0.025 へ変わりました。自分のトークン内訳から削減幅を先に見積もる手順と、倍率を定数で持つコードの直し方をまとめます。
訳文は自然なのに、実行時に落ちる翻訳がありました
多言語アプリの文言を Claude API で訳したとき、意味は正しいのに書式指定子だけが壊れることがあります。重大度で分けた受け入れ検査と、壊れた行だけを訳し直す修復ループを実装と実測でまとめました。
エージェントに「確定する」ツールを渡さない — 助言・下ごしらえ・確定で棚卸しする
課金や送信や公開といった取り消せない操作を、承認ゲートで止める前に、そもそもツール一覧へ登録しないための分け方です。三段の棚卸しと、確定が紛れていないかを調べる小さなスクリプトを添えました。
thinking ブロックを弾く 400 が出たとき、会話履歴のどこが書き換わっていたか
Claude Fable 5.1 から、thinking ブロックより前の system・tools・messages を書き換えたリクエストが 400 で弾かれるようになりました。自分のエージェントループが該当するかを1リクエストで確かめる手順と、system の組み立て直し・履歴の切り詰めを書き換えなしのやり方へ移す実装をまとめます。
モデルIDを一括置換する前に、手元の CLI が抱えるカタログを引きます
新しい世代が出ると、前の世代のモデルIDが急に古く見えます。インストール済みの実行ファイルに埋め込まれたカタログを引き、一致・日付不一致・書式破損の三段に仕分けてから直す手順を、実測値とスクリプトつきでまとめました。
Sonnet 5 の9月の値上げは行われません。7月に立てた見込みを公式の価格表から組み直す
Sonnet 5 の導入価格 2ドル/10ドルは、9月1日に3ドル/15ドルへ上がる予定でした。その引き上げは行われず、導入価格がそのまま標準価格になっています。手元の usage から実効コストを出し直す手順を、動くコードとともにまとめました。
サーバーレスに置いた MCP サーバーで、listen ストリームが張り直され続けていました
エラーは何も出ていないのに、MCP サーバーへの接続だけが増え続ける。固定タイムアウトで切られるストリームと再購読が噛み合ったときの挙動を、最小の再現コードで確かめました。
長考の途中で切れる接続は、上流ではなく中継が作っています
自作プロキシや Worker を挟んだ途端、Claude Code が長い思考の最中に切断される。原因は上流でもモデルでもなく、中継がバイトの流れを止めていることにあります。6通りの中継を並べて切り分け、本番に入れる前に確かめる手順まで整理しました。
Workbench が止まる8月17日までに、prompt tools API を手元のスクリプトへ移す
旧 Workbench と3つの実験的プロンプトエンドポイントが2026年8月17日に終了します。依存箇所の数え方と、templatize_prompt・improve_prompt を手元のスクリプトへ移す実装を、実際の出力つきでまとめました。
会話の途中でツールを差し替える — プロンプトキャッシュを守るツールレジストリの設計
ターン間でツールを追加・削除できるようになった一方、ツール定義はキャッシュプレフィックスの最前列にあります。12種類の変更を指紋で実測し、安定コアと揮発テールに分けるレジストリ設計とガード実装をまとめました。
400文字だけ残したはずのツール出力が、1MB を握り続けていた
自作の MCP サーバーやツールラッパーで出力を切り詰めても、Node の sliced string は元の全文を握り続けます。境界が13文字であること、平坦化が効く書き方と効かない書き方、ヒープスナップショットから親を数える監査スクリプトまで、すべて実測して記録しました。
ツール出力10万文字の境界で消える一行 — 実測から組み立てた出力封筒の設計
エージェントのツール出力が10万文字を超えると全文はファイルへ退避され、モデルには先頭を切り取ったプレビューだけが渡ります。手元のリポジトリで実測した生存率と、判断材料を先頭へ押し出す出力封筒の実装をまとめました。
Mcp-Session-Id を前提にしない MCP サーバーへ — 状態の置き場所を作り直す
MCP仕様の2026-07-28リリース候補でMcp-Session-Idヘッダーの廃止が示されました。自作リモートMCPサーバーのセッション結合を監査スクリプトで数え、状態を三つに仕分けて署名付きカーソルへ移行するまでの実測記録です。移行の順番と旧方式の外し方まで具体的に書いています。
メモリストアの棚卸しが半分しか返らない — path_prefix セグメント一致への移行
agent-memory-2026-07-22 で memories.list が変わりました。順序固定・depth 厳格化・path_prefix のセグメント一致。件数が音もなく半減した実例と、破壊的変更に耐える棚卸し層、呼び出し箇所を ast で洗い出す方法、depth=1 再帰の走査コストの実測をまとめます。
共通エージェント定義をセッション単位で使い分ける運用設計
Managed Agents で土台のエージェント定義を1つに畳み、バージョン固定とセッションローカルな上書きを使い分ける設計を、検証付きのコードと運用の落とし穴とともにまとめました。
プロンプトキャッシュを入れたのに請求が下がらなかったとき — cache_read を計測してヒット率の穴を塞ぐ運用メモ
cache_control を付けたのに Claude API の請求が下がらない。原因を推測で潰す前に cache_read と cache_creation を毎リクエスト記録し、ヒット率の穴を非決定プレフィックス・TTL 失効・しきい値未満の3系統に切り分ける運用メモです。
ユーザーに届くAI生成の短文を、公開前に二段ゲートで止める
アプリでユーザーに届くAI生成の短文を、決定的ルール層とClaude分類層の二段ゲートで公開前に検査する設計です。fail-closedを芯に据えた判定統合、生成時に検疫して配信時は取り出すだけの構成、生成数で効くコスト設計、人間のサンプリング体制まで実装コード付きで整理しました。
検索の精度は二段目で決まる — 埋め込みで粗く集め、Claude で並べ直す個人ナレッジ検索
埋め込み検索だけでは「意味は近いが答えではない」候補が上位に残ります。粗く集めた候補を Claude で並べ直す二段検索の設計を、構造化スコアリング・棄権・コスト試算まで個人ナレッジ検索の実装でまとめました。
Claude API の同時実行を束ねる — シングルフライトで重複推論とキャッシュ・スタンピードを防ぐ
同一プロンプトが同時に何度も Claude へ飛ぶ重複推論を、シングルフライト（request coalescing）で束ねる設計です。プロセス内・分散環境の実装、ジッター付きリトライ、負のキャッシュまで実測付きでまとめました。
画像を原寸で送るか縮小するか — Opus 4.7 の高解像度ビジョンで1枚ごとに解像度を決めるコスト設計
Opus 4.7 の高解像度ビジョンで壁紙の細部分類は上がったのに、全部を原寸で送ったら週のトークンが跳ねました。1枚ごとに解像度と使うモデルを決める preflight を設計し、精度を保ったままコストを下げた実測を残します。
Extended Thinking を入れたのに精度は横ばい、請求だけ伸びていたとき — 思考トークンの限界効用を計測して budget を決める運用メモ
budget_tokens を大きめに固定したまま、精度が変わらないのに請求だけ伸びていく。思考トークンを台帳に残し、budget を1段上げたときの正解率の伸びを限界効用として計測して、根拠のある値に落とす運用メモです。
Claude API の 413 request too large を設計で避ける — 送信前サイズ見積もりと分割の実装
長文と画像と tool_result を1リクエストに詰めすぎると Claude API は 413 request too large で落ちます。32MB の壁・base64 の膨張・処理段階で起きる隠れた上限を実測し、送信前にサイズを見積もって安全に分割する設計をコード付きでまとめました。
APIキーに有効期限を付けると、失効は事故ではなく予定になる — 無人運用の鍵カレンダー設計
Console で APIキーに有効期限を設定できるようになりました。無人で回している夜間ジョブを止めないために、二重鍵の重ね替えとローカルの失効台帳で「予定された失効」を運用に組み込む方法をまとめます。
非ストリーミングの長い応答が10分の壁で黙って二重課金されていた — SDK既定のタイムアウトと自動リトライを設計し直す
Anthropic SDK の既定タイムアウト10分と自動リトライ2回が、長い非ストリーミング応答を裏で二重に走らせて課金することがあります。発生の仕組みと、ストリーミング切替・明示的な timeout/max_retries・ローカル台帳で止める実装を、実測値とともにまとめました。
生成した壁紙が既存カタログに似すぎていないか — 知覚ハッシュで絞り Claude Vision で最終判定する近重複検出
SHA256の完全一致ではすり抜ける再配色・軽いクロップのニアデュプを、知覚ハッシュの事前フィルタとClaude Visionの最終判定で捕まえる二段構えのパイプライン。実測のprecision較正とコスト設計まで、壁紙カタログの個人運用から共有します。
本番で観測した引数分布からツールスキーマを締め直す
Claudeのツール呼び出しが渡してくる引数を本番で丸ごと記録し、その分布からJSON Schemaにenumやpatternを足して締め直す運用手法を整理しました。緩いスキーマが生む意味のドリフトの実例、段階的に締める手順、締め直し前後の実測値、状況別の推奨まで計測コード付きで紹介します。
Whisper が無音区間に『ご視聴ありがとうございました』を書き足していたとき — 日本語文字起こしの幻聴を計測して潰す運用メモ
Whisper の日本語文字起こしは無音や雑音の区間で存在しない定型句を挿入します。no_speech_prob と avg_logprob で幻聴を計測し、VAD で無音を落とし、Claude に検証させて残った混入を潰すまでの実装と運用手順をまとめました。
画像分類の信頼度を鵜呑みにしない — クラス別しきい値の較正と棄却ルーティング
全体の一致率は92%なのに特定カテゴリだけ71%——Claude Visionの自己申告confidenceを鵜呑みにせず、クラス別にしきい値を較正して低信頼の判定を人手キューへ棄却する設計を実測記録として残します。検証セットの規模、較正が静かに腐る問題、採用の判断基準まで扱います。