claude-api

Claude API（Anthropic Messages API）

ステータス：本番環境で使用可能 | SDK：@anthropic-ai/[email protected]

---

クイックスタート（5 分）

Node.js

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const message = await client.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [
    { role: 'user', content: 'Hello, Claude!' },
  ],
});

console.log(message.content[0].text);

Cloudflare Workers

const response = await fetch('https://api.anthropic.com/v1/messages', {
  method: 'POST',
  headers: {
    'x-api-key': env.ANTHROPIC_API_KEY,
    'anthropic-version': '2023-06-01',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    model: 'claude-sonnet-4-5-20250929',
    max_tokens: 1024,
    messages: [{ role: 'user', content: 'Hello!' }],
  }),
});

const data = await response.json();
console.log(data.content[0].text);

ストリーミング、キャッシュ、ツールを含む完全なセットアップについては、references/setup-guide.md を読み込んでください。

---

重要なルール

必ず行うこと ✅

1. API キーには環境変数を使用する（ハードコードは絶対にしない）
2. max_tokens を明示的に設定する（必須パラメーター）
3. モデルのバージョンを固定する（claude-3-5-sonnet-latest ではなく claude-sonnet-4-5-20250929）
4. 繰り返し使用するコンテンツにはプロンプトキャッシュを有効にする（コストを 90% 削減）
5. UX を向上させるため、長い応答はストリーミングする（stream: true）
6. エラーを処理する — 429、529 エラーに対する再試行ロジックを実装する
7. 入力を検証する — 送信前にユーザーメッセージをサニタイズする
8. コストを監視する — トークン使用量を追跡する
9. タイムアウトを設定する — リクエストのハングを防ぐ
10. ツール使用を適切に行う — 後続のメッセージで tool_result を返す

絶対に行わないこと ❌

1. クライアント側のコードでAPI キーを公開しない
2. max_tokens を省略しない — 設定しないと API エラーになります
3. stop_reason を無視しない — tool_use、end_turn、max_tokens を確認する
4. コンテンツブロックが 1 つだけだと思い込まない — content は配列です
5. 古いモデルを使用しない — 特定のバージョンに固定する
6. エラー処理を省略しない — API 呼び出しは失敗することがあります
7. メッセージのロールを混在させない — user と assistant を正しく交互にする
8. レート制限を無視しない — 指数バックオフを実装する
9. ログやデータベースにAPI キーを保存しない
10. 入力検証を省略しない — インジェクション攻撃を防ぐ

---

よくあるエラー上位 3 件（問題の 80% を防止）

エラー #1：レート制限 429

症状：429 Too Many Requests: Number of request tokens has exceeded your per-minute rate limit

解決策：retry-after ヘッダーを使った指数バックオフを実装する

async function handleRateLimit(requestFn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await requestFn();
    } catch (error) {
      if (error.status === 429) {
        const retryAfter = error.response?.headers?.['retry-after'];
        const delay = retryAfter ? parseInt(retryAfter) * 1000 : 1000 * Math.pow(2, attempt);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
}

予防策：レート制限ヘッダーを監視し、ティアをアップグレードして、バックオフを実装する

---

エラー #2：プロンプトキャッシュが有効にならない

症状：cache_control ブロックがあるにもかかわらずコストが高く、cache_read_input_tokens: 0 となる

解決策：1024 トークン以上の最後のブロックに cache_control を設定する

// ❌ Wrong - cache_control not at end
{
  type: 'text',
  text: DOCUMENT,
  cache_control: { type: 'ephemeral' },  // Wrong position
},
{
  type: 'text',
  text: 'Additional text',
}

// ✅ Correct - cache_control at end
{
  type: 'text',
  text: DOCUMENT + '\n\nAdditional text',
  cache_control: { type: 'ephemeral' },  // Correct position
}

予防策：コンテンツを 1024 トークン以上にし、キャッシュするコンテンツを同一に保ち、使用状況を監視する

完全なキャッシュ戦略については、references/prompt-caching-guide.md を読み込んでください。

---

エラー #3：ツール使用の応答形式エラー

症状：invalid_request_error: tools[0].input_schema is invalid

解決策：適切な JSON Schema を使った有効なツールスキーマにする

// ✅ Valid tool schema
{
  name: 'get_weather',
  description: 'Get current weather',
  input_schema: {
    type: 'object',           // Must be 'object'
    properties: {
      location: {
        type: 'string',       // Valid JSON Schema types
        description: 'City'   // Optional but recommended
      }
    },
    required: ['location']    // List required fields
  }
}

// ✅ Valid tool result
{
  type: 'tool_result',
  tool_use_id: block.id,      // Must match tool_use id
  content: JSON.stringify(result)  // Convert to string
}

予防策：スキーマを検証し、tool_use_id を正確に一致させ、結果を文字列化する

12 件すべてのエラーについては、references/tool-use-patterns.md と references/top-errors.md を読み込んでください。

---

よくあるユースケース（簡単なパターン）

ストリーミング応答

const stream = await client.messages.stream({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Write a story.' }],
});

for await (const event of stream) {
  if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') {
    process.stdout.write(event.delta.text);
  }
}

読み込む：templates/streaming-chat.ts

---

プロンプトキャッシュ（コストを 90% 削減）

const message = await client.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  system: [
    {
      type: 'text',
      text: 'Long system prompt...',
      cache_control: { type: 'ephemeral' },
    },
  ],
  messages: [{ role: 'user', content: 'Question?' }],
});

キャッシュの有効期間は 5 分で、キャッシュされたトークンのコストを 90% 削減できます

読み込む：references/prompt-caching-guide.md と templates/prompt-caching.ts

---

ツール使用（関数呼び出し）

const message = await client.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  tools: [{
    name: 'get_weather',
    description: 'Get weather for a location',
    input_schema: {
      type: 'object',
      properties: { location: { type: 'string' } },
      required: ['location'],
    },
  }],
  messages: [{ role: 'user', content: 'Weather in SF?' }],
});

if (message.stop_reason === 'tool_use') {
  const toolUse = message.content.find(b => b.type === 'tool_use');
  // Execute tool and send result back...
}

読み込む：references/tool-use-patterns.md と templates/tool-use-basic.ts

---

ビジョン（画像の理解）

const message = await client.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{
    role: 'user',
    content: [
      {
        type: 'image',
        source: {
          type: 'base64',
          media_type: 'image/jpeg',
          data: base64Image,
        },
      },
      { type: 'text', text: 'What is in this image?' },
    ],
  }],
});

対応形式：JPEG、PNG、WebP、GIF（最大 5MB）

読み込む：references/vision-capabilities.md と templates/vision-image.ts

---

拡張思考モード

const message = await client.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 4096,
  thinking: {
    type: 'enabled',
    budget_tokens: 2000,
  },
  messages: [{ role: 'user', content: 'Solve complex problem...' }],
});

const thinking = message.content.find(b => b.type === 'thinking')?.thinking;
const answer = message.content.find(b => b.type === 'text')?.text;

読み込む：templates/extended-thinking.ts

---

モデルのバージョン（現行）

最新モデル：

• claude-sonnet-4-5-20250929 - 推奨（最高のパフォーマンス）
• claude-sonnet-4-20250514 - 安定版
• claude-3-7-sonnet-20250219 - 旧世代
• claude-3-5-sonnet-20241022 - レガシー

必ず特定のバージョンに固定してください（-latest サフィックスは使用しない）

---

リファレンスを読み込むタイミング

次の場合に references/setup-guide.md を読み込んでください：

• Claude API を初めて使う方で、セットアップの手順全体を確認したい場合
• Node.js または Cloudflare Workers をゼロからセットアップする場合
• 本番環境へのデプロイチェックリストや、プラットフォーム別のヒントが必要な場合
• 基本的なセットアップの問題（API キー、認証、環境）のトラブルシューティングを行う場合

次の場合に references/prompt-caching-guide.md を読み込んでください：

• 繰り返し使うコンテンツのコストを 90% 削減したい場合
• 大きなシステムプロンプト、ドキュメント、コードベースをコンテキストで使用する場合
• ベンチマークやコスト計算を含む、詳細なキャッシュ戦略が必要な場合
• 会話履歴のキャッシュを使って複数ターンの会話を最適化する場合
• キャッシュが有効にならない問題やキャッシュミスのトラブルシューティングを行う場合

次の場合に references/tool-use-patterns.md を読み込んでください：

• 関数呼び出しとツール定義を実装する場合
• ツール実行ループのパターンや、複数ターンにわたるツールの使用方法が必要な場合
• 型安全なツールのための Zod バリデーション例を確認したい場合
• ツール使用時のレスポンス形式エラーをトラブルシューティングする場合

次の場合に references/vision-capabilities.md を読み込んでください：

• Claude で画像を処理する場合（OCR、分析、説明）
• 画像形式の要件やバリデーションロジックが必要な場合
• ビジョン機能のユースケースやベストプラクティスを確認したい場合
• ビジョン機能をツールやプロンプトキャッシュと組み合わせる場合

次の場合に references/api-reference.md を読み込んでください：

• API パラメーターの完全なリファレンスや、リクエスト／レスポンスのスキーマが必要な場合
• 特定のフィールドやコンテンツブロックの種類を調べる場合
• エンドポイントの詳細、認証ヘッダー、モデル ID を確認したい場合
• ストリーミングイベントの種類や SSE 形式の詳細が必要な場合

次の場合に references/top-errors.md を読み込んでください：

• API エラーが発生した場合（解決策を含む、ドキュメント化された全 12 件のエラー）
• エラーコードのリファレンス（400、401、429、529 など）が必要な場合
• 包括的な予防策を確認したい場合
• 堅牢なエラー処理とリトライロジックを実装する場合

次の場合に references/rate-limits.md を読み込んでください：

• 大量利用やスケーリング戦略を計画する場合
• 429 のレート制限エラーが繰り返し発生する場合
• ティアごとの制限情報やアップグレード方法が必要な場合
• 制限内に収まるようリクエストパターンを最適化する場合

---

同梱リソースの使用

リファレンス（references/）

• setup-guide.md - セットアップ全体（Node.js + Cloudflare Workers + Next.js）
• api-reference.md - API パラメーターの完全なリファレンス + スキーマ
• prompt-caching-guide.md - コストを 90% 削減するためのガイド + ベンチマーク
• tool-use-patterns.md - 関数呼び出しのパターン + Zod の例
• vision-capabilities.md - 画像理解のガイド + バリデーション
• top-errors.md - 解決策 + 予防策を含む全 12 件のエラー
• rate-limits.md - ティアごとの制限 + ベストプラクティス

テンプレート（templates/）

• basic-chat.ts - シンプルなチャットの例
• streaming-chat.ts - SSE を使ったストリーミングの実装
• prompt-caching.ts - ベンチマーク付きのキャッシュ例
• tool-use-basic.ts - 基本的なツール使用パターン
• tool-use-advanced.ts - 高度な複数ターンのツール使用パターン
• vision-image.ts - バリデーション付きのビジョン機能の例
• extended-thinking.ts - 拡張思考モード
• error-handling.ts - エラー処理全体
• nodejs-example.ts - Node.js アプリ全体
• cloudflare-worker.ts - CF Worker 全体
• nextjs-api-route.ts - Next.js API ルート
• package.json - 依存関係

---

プラットフォーム統合

Node.js：bun add @anthropic-ai/sdk → テンプレートを使用：nodejs-example.ts、basic-chat.ts

Cloudflare Workers：fetch API を使用 → テンプレートを使用：cloudflare-worker.ts

Next.js：bun add @anthropic-ai/sdk → テンプレートを使用：nextjs-api-route.ts

---

本番環境チェックリスト

• API キーを安全に保管している（環境変数）
• エラー処理を実装している（401、429、400、529）
• 指数バックオフを使ったレート制限を設定している
• 繰り返し使うコンテンツにプロンプトキャッシュを有効にしている
• 長いレスポンスにストリーミングを使っている
• 入力のバリデーション + 出力のサニタイズを行っている
• モニタリングとコスト追跡を行っている
• タイムアウトを設定している
• モデルのバージョンを固定している
• max_tokens を適切に設定している

---

関連スキル

• openai-api - 比較用の OpenAI Chat Completions
• claude-agent-sdk - より高レベルな Claude SDK
• ai-sdk-core - Vercel AI SDK（Claude をサポート）

---

公式ドキュメント

• Messages API: https://docs.anthropic.com/en/api/messages
• プロンプトキャッシュ: https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
• ツールの使用: https://docs.anthropic.com/en/docs/build-with-claude/tool-use
• ビジョン: https://docs.anthropic.com/en/docs/build-with-claude/vision
• 拡張思考: https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking

---

質問や問題がありますか？

1. エラーの解決方法については references/top-errors.md を確認してください
2. セットアップ全体については references/setup-guide.md を参照してください
3. コストの最適化については references/prompt-caching-guide.md を参照してください
4. 動作するサンプルについては templates/ からテンプレートを読み込んでください