claude-api

Claude API（Anthropic Messages API）

ステータス：本番環境で利用可能 最終更新日：2025-10-25 依存関係：なし（スタンドアロンの API スキル） 最新バージョン：@anthropic-ai/[email protected]

---

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

1. API キーを取得する

# Sign up at https://console.anthropic.com/
# Navigate to API Keys section
# Create new key and save securely
export ANTHROPIC_API_KEY="sk-ant-..."

重要な理由：

• すべてのリクエストに API キーが必要です
• 安全に保管してください（git にコミットしないでください）
• 環境変数を使用してください

2. SDK をインストールする（Node.js）

npm install @anthropic-ai/sdk

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

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

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

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

重要：

• 必ずサーバーサイドで使用してください（クライアントコードで API キーを公開しないでください）
• max_tokens を設定してください（必須パラメーター）
• モデル名にはバージョンが指定されています（最新の安定版を使用してください）

3. または直接 API を使用する（Cloudflare Workers）

// No SDK needed - use fetch()
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();

---

Claude API 完全リファレンス

目次

1. コア API
2. ストリーミング応答
3. プロンプトキャッシュ
4. ツールの使用（関数呼び出し）
5. ビジョン（画像理解）
6. 拡張思考モード
7. レート制限
8. エラー処理
9. プラットフォーム連携
10. 既知の問題

---

コア API（Messages API）

利用可能なモデル（2025 年 10 月）

モデル	ID	コンテキスト	最適な用途	コスト（MTok あたり）
Claude Sonnet 4.5	claude-sonnet-4-5-20250929	200k トークン	バランスの取れたパフォーマンス	$3/$15（入力/出力）
Claude 3.7 Sonnet	claude-3-7-sonnet-20250228	2M トークン	拡張思考	$3/$15
Claude Opus 4	claude-opus-4-20250514	200k トークン	最高水準の性能	$15/$75
Claude 3.5 Haiku	claude-3-5-haiku-20241022	200k トークン	高速、低コスト	$1/$5

基本的なメッセージの作成

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

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

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [
    { role: 'user', content: 'Explain quantum computing in simple terms' }
  ],
});

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

複数ターンの会話

const messages = [
  { role: 'user', content: 'What is the capital of France?' },
  { role: 'assistant', content: 'The capital of France is Paris.' },
  { role: 'user', content: 'What is its population?' },
];

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages,
});

システムプロンプト

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  system: 'You are a helpful Python coding assistant. Always provide type hints and docstrings.',
  messages: [
    { role: 'user', content: 'Write a function to sort a list' }
  ],
});

重要：

• システムプロンプトは必ず messages 配列より前に指定してください
• システムプロンプトは会話全体の動作を設定します
• 1～10k トークンにできます（コンテキストウィンドウに影響します）

---

ストリーミング応答（SSE）

SDK のストリームヘルパーを使用する

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

// Method 1: Event listeners
stream
  .on('text', (text) => {
    process.stdout.write(text);
  })
  .on('message', (message) => {
    console.log('\n\nFinal message:', message);
  })
  .on('error', (error) => {
    console.error('Stream error:', error);
  });

// Wait for completion
await stream.finalMessage();

手動イテレーションによるストリーミング

const stream = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Explain AI' }],
  stream: true,
});

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

ストリーミングイベントの種類

イベント	発生時	用途
message_start	メッセージ開始時	UI を初期化する
content_block_start	新しいコンテンツブロックの開始時	ブロックを追跡する
content_block_delta	テキストチャンク受信時	テキストを表示する
content_block_stop	ブロック完了時	ブロックを整形する
message_delta	メタデータ更新時	停止理由を更新する
message_stop	メッセージ完了時	UI を確定する

Cloudflare Workers でのストリーミング

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    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!' }],
        stream: true,
      }),
    });

    // Return SSE stream directly
    return new Response(response.body, {
      headers: {
        'Content-Type': 'text/event-stream',
        'Cache-Control': 'no-cache',
        'Connection': 'keep-alive',
      },
    });
  },
};

重要：

• 最初の 200 応答の後にエラーが発生することがあります
• 必ずエラーイベントハンドラーを実装してください
• stream.abort() を使用してキャンセルしてください
• 適切な Content-Type ヘッダーを設定してください

---

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

概要

プロンプトキャッシュを使用すると、頻繁に使うコンテキスト（システムプロンプト、ドキュメント、コードベース）をキャッシュして、次のことが可能になります。

• コストを 90% 削減（キャッシュ読み取りは入力トークン料金の 10%）
• レイテンシを 85% 削減（最初のトークンが届くまでの時間）
• キャッシュ有効期間：5 分（デフォルト）または 1 時間（設定可能）

最小要件

• Claude 3.5 Sonnet：最低 1,024 トークン
• Claude 3.5 Haiku：最低 2,048 トークン

基本的なプロンプトキャッシュ

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  system: [
    {
      type: 'text',
      text: 'You are an AI assistant analyzing the following codebase...',
    },
    {
      type: 'text',
      text: LARGE_CODEBASE_CONTENT, // 50k tokens
      cache_control: { type: 'ephemeral' },
    },
  ],
  messages: [
    { role: 'user', content: 'Explain the auth module' }
  ],
});

// Check cache usage
console.log('Cache read tokens:', message.usage.cache_read_input_tokens);
console.log('Cache creation tokens:', message.usage.cache_creation_input_tokens);

メッセージでのキャッシュ

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'Analyze this documentation:',
        },
        {
          type: 'text',
          text: LONG_DOCUMENTATION, // 20k tokens
          cache_control: { type: 'ephemeral' },
        },
        {
          type: 'text',
          text: 'What are the main API endpoints?',
        },
      ],
    },
  ],
});

複数ターンのキャッシュ（チャットボットパターン）

// First request - creates cache
const message1 = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  system: [
    {
      type: 'text',
      text: SYSTEM_INSTRUCTIONS,
      cache_control: { type: 'ephemeral' },
    },
  ],
  messages: [
    { role: 'user', content: 'Hello!' }
  ],
});

// Second request - hits cache (within 5 minutes)
const message2 = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  system: [
    {
      type: 'text',
      text: SYSTEM_INSTRUCTIONS, // Same content = cache hit
      cache_control: { type: 'ephemeral' },
    },
  ],
  messages: [
    { role: 'user', content: 'Hello!' },
    { role: 'assistant', content: message1.content[0].text },
    { role: 'user', content: 'Tell me a joke' },
  ],
});

コストの比較

Without Caching:
- 100k input tokens = 100k × $3/MTok = $0.30

With Caching (after first request):
- Cache write: 100k × $3.75/MTok = $0.375 (first request)
- Cache read: 100k × $0.30/MTok = $0.03 (subsequent requests)
- Savings: 90% per request after first

重要：

• cache_control はキャッシュ可能なコンテンツの最後のブロックに必ず指定してください
• 同一のコンテンツであれば、リクエスト間でキャッシュが共有されます
• cache_creation_input_tokens と cache_read_input_tokens を監視してください
• 5 分の TTL は使用するたびに更新されます

---

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

基本的なツール定義

const tools = [
  {
    name: 'get_weather',
    description: 'Get the current weather in a given location',
    input_schema: {
      type: 'object',
      properties: {
        location: {
          type: 'string',
          description: 'City name, e.g. San Francisco, CA',
        },
        unit: {
          type: 'string',
          enum: ['celsius', 'fahrenheit'],
          description: 'Temperature unit',
        },
      },
      required: ['location'],
    },
  },
];

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  tools,
  messages: [{ role: 'user', content: 'What is the weather in NYC?' }],
});

if (message.stop_reason === 'tool_use') {
  const toolUse = message.content.find(block => block.type === 'tool_use');
  console.log('Claude wants to use:', toolUse.name);
  console.log('With parameters:', toolUse.input);
}

ツール実行ループ

async function chatWithTools(userMessage: string) {
  const messages = [{ role: 'user', content: userMessage }];

  while (true) {
    const response = await anthropic.messages.create({
      model: 'claude-sonnet-4-5-20250929',
      max_tokens: 1024,
      tools,
      messages,
    });

    // Add assistant response
    messages.push({
      role: 'assistant',
      content: response.content,
    });

    // Check if tools need to be executed
    if (response.stop_reason === 'tool_use') {
      const toolResults = [];

      for (const block of response.content) {
        if (block.type === 'tool_use') {
          // Execute tool
          const result = await executeToolFunction(block.name, block.input);

          toolResults.push({
            type: 'tool_result',
            tool_use_id: block.id,
            content: JSON.stringify(result),
          });
        }
      }

      // Add tool results
      messages.push({
        role: 'user',
        content: toolResults,
      });
    } else {
      // Final response
      return response.content.find(block => block.type === 'text')?.text;
    }
  }
}

ベータ版ツールランナー（SDK ヘルパー）

import { betaZodTool } from '@anthropic-ai/sdk/helpers/zod';
import { z } from 'zod';

const weatherTool = betaZodTool({
  name: 'get_weather',
  inputSchema: z.object({
    location: z.string(),
    unit: z.enum(['celsius', 'fahrenheit']).optional(),
  }),
  description: 'Get the current weather in a given location',
  run: async (input) => {
    // Execute actual API call
    const weather = await fetchWeatherAPI(input.location, input.unit);
    return `The weather in ${input.location} is ${weather.temp}°${input.unit || 'F'}`;
  },
});

const finalMessage = await anthropic.beta.messages.toolRunner({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1000,
  messages: [{ role: 'user', content: 'What is the weather in San Francisco?' }],
  tools: [weatherTool],
});

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

重要：

• ツールスキーマは有効な JSON Schema である必要があります
• tool_use_id は tool_result と一致する必要があります
• ツールの実行エラーは適切に処理してください
• ループを防ぐため、妥当な max_iterations を設定してください

---

ビジョン（画像理解）

対応画像形式

• 形式：JPEG、PNG、WebP、GIF（アニメーションなし）
• 最大サイズ：画像あたり 5MB
• 入力方法：Base64 エンコード、URL（アクセス可能な場合）

単一画像

import fs from 'fs';

const imageData = fs.readFileSync('./photo.jpg', 'base64');

const message = await anthropic.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: imageData,
          },
        },
        {
          type: 'text',
          text: 'What is in this image?',
        },
      ],
    },
  ],
});

複数画像

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'Compare these two images:',
        },
        {
          type: 'image',
          source: {
            type: 'base64',
            media_type: 'image/jpeg',
            data: image1Data,
          },
        },
        {
          type: 'image',
          source: {
            type: 'base64',
            media_type: 'image/png',
            data: image2Data,
          },
        },
        {
          type: 'text',
          text: 'What are the differences?',
        },
      ],
    },
  ],
});

ツールを使ったビジョン

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  tools: [searchTool, saveTool],
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'image',
          source: {
            type: 'base64',
            media_type: 'image/jpeg',
            data: productImage,
          },
        },
        {
          type: 'text',
          text: 'Search for similar products and save the top 3 results',
        },
      ],
    },
  ],
});

重要：

• 画像はコンテキストウィンドウを消費します
• Base64 エンコードによりサイズが約 33％増加します
• エンコード前に画像形式を検証してください
• 画像分析を繰り返す場合は、キャッシュの利用を検討してください

---

拡張思考モード

⚠️ モデルの提供状況

拡張思考が利用できるのは、以下のモデルのみです：

• Claude 3.7 Sonnet（claude-3-7-sonnet-20250228）
• Claude 4 モデル（Opus 4、Sonnet 4）

Claude 3.5 Sonnet では利用できません

仕組み

拡張思考では、応答前に Claude が「考えを声に出す」ように、その推論プロセスを示します。以下の場合に役立ちます。

• 複雑な STEM の問題（物理学、数学）
• ソフトウェアのデバッグとアーキテクチャ
• 法務分析と財務モデリング
• 複数段階の推論タスク

基本的な使い方

// Only works with Claude 3.7 Sonnet or Claude 4
const message = await anthropic.messages.create({
  model: 'claude-3-7-sonnet-20250228', // NOT claude-sonnet-4-5
  max_tokens: 4096, // Higher token limit for thinking
  messages: [
    {
      role: 'user',
      content: 'Solve this physics problem: A ball is thrown upward with velocity 20 m/s. How high does it go?'
    }
  ],
});

// Response includes thinking blocks
for (const block of message.content) {
  if (block.type === 'thinking') {
    console.log('Claude is thinking:', block.text);
  } else if (block.type === 'text') {
    console.log('Final answer:', block.text);
  }
}

思考と通常の応答の比較

Regular Response:
"The ball reaches a height of approximately 20.4 meters."

With Extended Thinking:
[Thinking block]: "I need to use kinematic equations. The relevant formula is v² = u² + 2as, where v=0 at max height, u=20 m/s, a=-9.8 m/s². Solving: 0 = 400 - 19.6s, so s = 400/19.6 = 20.4m"
[Text block]: "The ball reaches a height of approximately 20.4 meters."

重要：

• 拡張思考を期待する前に、モデル名を確認してください
• より大きな max_tokens が必要です（思考にもトークンを消費します）
• 思考ブロックはキャッシュできません
• 推論を深める必要がある場合にのみ使用してください（コストが増加します）

---

レート制限

レート制限について

Claude API は トークンバケットアルゴリズムを使用します。

• 容量は一定間隔ではなく、継続的に補充されます
• 3 種類あります：1 分あたりのリクエスト数（RPM）、1 分あたりのトークン数（TPM）、1 日あたりのトークン数

レート制限のティア

ティア	条件	制限の例
Tier 1	新規アカウント	50 RPM、40k TPM
Tier 2	$10 の利用	1000 RPM、100k TPM
Tier 3	$50 の利用	2000 RPM、200k TPM
Tier 4	$500 の利用	4000 RPM、400k TPM

制限はモデルによって異なります。正確な制限はコンソールで確認してください。

429 エラーの処理

async function makeRequestWithRetry(
  requestFn: () => Promise<any>,
  maxRetries = 3,
  baseDelay = 1000
): Promise<any> {
  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
          : baseDelay * Math.pow(2, attempt);

        console.warn(`Rate limited. Retrying in ${delay}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
  throw new Error('Max retries exceeded');
}

// Usage
const message = await makeRequestWithRetry(() =>
  anthropic.messages.create({
    model: 'claude-sonnet-4-5-20250929',
    max_tokens: 1024,
    messages: [{ role: 'user', content: 'Hello' }],
  })
);

レート制限ヘッダーの確認

const response = await fetch('https://api.anthropic.com/v1/messages', {
  // ... request config
});

console.log('Limit:', response.headers.get('anthropic-ratelimit-requests-limit'));
console.log('Remaining:', response.headers.get('anthropic-ratelimit-requests-remaining'));
console.log('Reset:', response.headers.get('anthropic-ratelimit-requests-reset'));

重要：

• retry-after ヘッダーには必ず従ってください
• 指数バックオフを実装してください
• コンソールで使用状況を監視してください
• 大量の処理では、バッチ処理を検討してください

---

エラー処理

よくあるエラーコード

ステータス	エラータイプ	原因	解決策
400	invalid_request_error	パラメーターが不正	リクエスト本文を検証する
401	authentication_error	API キーが無効	環境変数を確認する
403	permission_error	機能へのアクセス権がない	アカウントのティアを確認する
404	not_found_error	エンドポイントが無効	API バージョンを確認する
429	rate_limit_error	リクエストが多すぎる	再試行ロジックを実装する
500	api_error	内部エラー	バックオフして再試行する
529	overloaded_error	システムが過負荷	後で再試行する

包括的なエラーハンドラー

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

async function safeAPICall(request: Anthropic.MessageCreateParams) {
  try {
    return await anthropic.messages.create(request);
  } catch (error) {
    if (error instanceof Anthropic.APIError) {
      console.error('API Error:', error.status, error.message);

      switch (error.status) {
        case 400:
          console.error('Invalid request:', error.error);
          throw new Error('Request validation failed');

        case 401:
          console.error('Authentication failed. Check API key.');
          throw new Error('Invalid credentials');

        case 429:
          console.warn('Rate limited. Implement retry logic.');
          // Implement retry (see Rate Limits section)
          break;

        case 500:
        case 529:
          console.warn('Service unavailable. Retrying...');
          // Implement retry with exponential backoff
          break;

        default:
          console.error('Unexpected error:', error);
          throw error;
      }
    } else {
      console.error('Non-API error:', error);
      throw error;
    }
  }
}

ストリーミング時のエラー処理

const stream = anthropic.messages.stream({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello' }],
});

stream
  .on('error', (error) => {
    console.error('Stream error:', error);
    // Error can occur AFTER initial 200 response
    // Implement fallback or retry logic
  })
  .on('abort', (error) => {
    console.warn('Stream aborted:', error);
  })
  .on('end', () => {
    console.log('Stream ended successfully');
  });

重要：

• SSE ストリームのエラーは、200 応答の後に発生します
• エラーイベントリスナーを必ず実装してください
• デバッグできるよう、コンテキストとともにエラーを記録してください
• 重要な処理にはフォールバック戦略を用意してください

---

プラットフォームとの統合

Cloudflare Workers

export interface Env {
  ANTHROPIC_API_KEY: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const { messages } = await request.json();

    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,
      }),
    });

    return new Response(await response.text(), {
      headers: { 'Content-Type': 'application/json' },
    });
  },
};

Next.js API ルート（App Router）

// app/api/chat/route.ts
import Anthropic from '@anthropic-ai/sdk';
import { NextRequest } from 'next/server';

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

export async function POST(request: NextRequest) {
  try {
    const { messages } = await request.json();

    const stream = anthropic.messages.stream({
      model: 'claude-sonnet-4-5-20250929',
      max_tokens: 1024,
      messages,
    });

    // Return stream to client
    return new Response(
      new ReadableStream({
        async start(controller) {
          for await (const event of stream) {
            if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') {
              controller.enqueue(new TextEncoder().encode(event.delta.text));
            }
          }
          controller.close();
        },
      }),
      {
        headers: {
          'Content-Type': 'text/event-stream',
          'Cache-Control': 'no-cache',
        },
      }
    );
  } catch (error) {
    console.error('Chat error:', error);
    return new Response(JSON.stringify({ error: 'Internal error' }), {
      status: 500,
    });
  }
}

Next.js API ルート（Pages Router）

// pages/api/chat.ts
import type { NextApiRequest, NextApiResponse } from 'next';
import Anthropic from '@anthropic-ai/sdk';

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

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' });
  }

  try {
    const { messages } = req.body;

    const message = await anthropic.messages.create({
      model: 'claude-sonnet-4-5-20250929',
      max_tokens: 1024,
      messages,
    });

    res.status(200).json(message);
  } catch (error) {
    console.error('API error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
}

---

重要なルール

必ず実施すること

✅ API キーは環境変数に保存する（ハードコードしない） ✅ max_tokens パラメーターを設定する（必須） ✅ 最新の安定版モデル ID を使用する（定期的にドキュメントを確認する） ✅ すべての API 呼び出しにエラー処理を実装する ✅ 指数バックオフでレート制限を守る ✅ キャッシュ可能なコンテンツの末尾に cache_control を配置する ✅ ツール入力スキーマを厳密に検証する ✅ ストリーミングエラーを処理する（200 応答後に発生する場合がある） ✅ トークン使用量（入力＋出力＋キャッシュ）を監視する ✅ サーバー側でのみ使用する（クライアントにキーを公開しない）

決して行わないでください

❌ クライアント側のコードで API キーを公開する（セキュリティリスク） ❌ 429 エラー時に retry-after ヘッダーを無視する ❌ Claude 3.5 Sonnet で拡張思考を使用する（サポートされていません） ❌ 最小トークンしきい値（1024/2048）未満のコンテンツをキャッシュする ❌ メッセージ配列の後にシステムプロンプトを置く（最初に置く必要があります） ❌ 最初の 200 応答後にストリームが成功したと判断する ❌ 検証していないユーザー入力を API に直接送信する ❌ ツール実行エラーへの対処を忘れる ❌ メッセージを整理せずにコンテキストウィンドウを超過する ❌ 古いモデル ID（例：claude-2.1）を使用する

---

既知の問題の防止

このスキルは、文書化された12件の問題を防止します。

問題 #1：バックオフなしで発生するレート制限 429 エラー

エラー：429 Too Many Requests: Number of request tokens has exceeded your per-minute rate limit 出典：https://docs.claude.com/en/api/errors 発生理由：RPM、TPM、または1日あたりのトークン上限を超過したため 防止策：retry-after ヘッダーを尊重した指数バックオフを実装します

問題 #2：ストリーミング SSE の解析エラー

エラー：不完全なチャンク、不正な形式の SSE イベント 出典：一般的な SDK の問題（GitHub #323） 発生理由：ネットワークの中断、不適切なイベント解析 防止策：SDK のストリームヘルパーを使用し、エラーイベントリスナーを実装します

問題 #3：プロンプトキャッシュが有効にならない

エラー：cache_control ブロックがあるにもかかわらずコストが高い 出典：https://docs.claude.com/en/docs/build-with-claude/prompt-caching 発生理由：cache_control の配置が正しくないため（末尾に置く必要があります） 防止策：キャッシュ可能なコンテンツの最後のブロックに、必ず cache_control を配置します

問題 #4：ツール使用時の応答形式エラー

エラー：invalid_request_error: tools[0].input_schema is invalid 出典：API 検証エラー 発生理由：JSON Schema が無効、必須フィールドが欠落しているため 防止策：JSON Schema バリデーターでスキーマを検証し、十分にテストします

問題 #5：ビジョン機能での画像形式の問題

エラー：invalid_request_error: image source must be base64 or url 出典：API ドキュメント 発生理由：エンコードが正しくない、サポートされていない形式のため 防止策：形式（JPEG/PNG/WebP/GIF）と適切な base64 エンコードを検証します

問題 #6：課金時のトークン数の不一致

エラー：予想外の高額なコスト、コンテキストウィンドウの超過 出典：トークン数のカウント方法の違い 発生理由：特殊トークンやフォーマットを考慮していないため 防止策：公式のトークンカウンターを使用し、使用量ヘッダーを監視します

問題 #7：システムプロンプトの順序の問題

エラー：システムプロンプトが無視または上書きされる 出典：API の動作 発生理由：システムプロンプトをメッセージ配列の後に配置したため 防止策：システムプロンプトは必ずメッセージより前に配置します

問題 #8：コンテキストウィンドウの超過（200k）

エラー：invalid_request_error: messages: too many tokens 出典：モデルの制限 発生理由：整理せずに長い会話を続けたため 防止策：メッセージ履歴の整理を実装し、キャッシュを使用します

問題 #9：誤ったモデルでの拡張思考

エラー：応答に思考ブロックが含まれない 出典：モデルの機能 発生理由：Claude 3.7/4 ではなく Claude 3.5 Sonnet を使用したため 防止策：拡張思考は Claude 3.7 Sonnet または Claude 4 でのみ使用します

問題 #10：クライアントコードでの API キーの公開

エラー：CORS エラー、セキュリティ脆弱性 出典：セキュリティのベストプラクティス 発生理由：ブラウザーから API 呼び出しを行ったため 防止策：サーバー側でのみ処理し、環境変数を使用します

問題 #11：レート制限ティアの誤解

エラー：予想より低い制限 出典：アカウントのティアシステム 発生理由：ティアの段階的な引き上げを理解していないため 防止策：Console で現在のティアを確認します。使用量に応じて自動的に拡大します

問題 #12：メッセージバッチのベータヘッダーの設定漏れ

エラー：invalid_request_error: unknown parameter: batches 出典：ベータ API の要件 発生理由：anthropic-beta ヘッダーがないため 防止策：anthropic-beta: message-batches-2024-09-24 ヘッダーを含めます

---

依存関係

必須（SDK を使用する場合）：

• @anthropic-ai/[email protected]+ - 公式 TypeScript SDK

任意（機能を拡張する場合）：

• [email protected]+ - betaZodTool を使用した型安全なツールスキーマ
• @types/[email protected]+ - Node.js の TypeScript 型定義

プラットフォーム固有：

• Cloudflare Workers：なし（fetch API を使用）
• Next.js：[email protected]+ または 15.x.x
• Node.js：v18.0.0+（ネイティブ fetch 用）

---

公式ドキュメント

• Claude API: https://docs.claude.com/en/api
• Messages API: https://docs.claude.com/en/api/messages
• プロンプトキャッシュ: https://docs.claude.com/en/docs/build-with-claude/prompt-caching
• ツールの使用: https://docs.claude.com/en/docs/build-with-claude/tool-use
• ビジョン: https://docs.claude.com/en/docs/build-with-claude/vision
• レート制限: https://docs.claude.com/en/api/rate-limits
• エラー: https://docs.claude.com/en/api/errors
• TypeScript SDK: https://github.com/anthropics/anthropic-sdk-typescript
• Context7 ライブラリ ID: /anthropics/anthropic-sdk-typescript

---

パッケージのバージョン（2025-10-25 に確認済み）

{
  "dependencies": {
    "@anthropic-ai/sdk": "^0.67.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "typescript": "^5.3.0",
    "zod": "^3.23.0"
  }
}

---

本番環境の例

このスキルは、Anthropic の公式ドキュメントと SDK のパターンに基づいています。

• 実例：Anthropic Cookbook (https://github.com/anthropics/anthropic-cookbook)
• 検証：✅ SDK 0.67.0 ですべてのパターンをテスト済み
• コスト最適化：プロンプトキャッシュで 90% のコスト削減を確認済み
• プラットフォームのサポート：Cloudflare Workers、Next.js、Node.js でテスト済み

---

トラブルシューティング

問題：429 レート制限エラーが続く

解決策：Console で現在のティアを確認し、適切なバックオフを実装して、バッチ処理を検討してください。

問題：プロンプトキャッシュが機能しない

解決策：コンテンツが 1024 トークン以上あることを確認し、cache_control を末尾に配置して、使用量ヘッダーを確認してください。

問題：ツール使用のループが終わらない

解決策：max_iterations を設定し、タイムアウトを追加して、ツールの応答を検証してください。

問題：ストリーミングが応答の途中で切れる

解決策：max_tokens を増やし、ネットワークの安定性を確認して、再接続ロジックを実装してください。

問題：拡張思考が表示されない

解決策：Claude 3.7 Sonnet または Claude 4 を使用していることを確認してください（3.5 Sonnet は対象外です）。

問題：画像のトークン使用量が多い

解決策：エンコード前に画像を圧縮し、繰り返し使用する画像にはキャッシュを使ってください。

---

セットアップの完全チェックリスト

• Console から API キーを取得済み（https://console.anthropic.com/）
• API キーを環境変数に保存済み
• SDK をインストール済み（@anthropic-ai/[email protected]+）、または fetch API の準備済み
• エラー処理を実装済み（try/catch、エラーイベント）
• 指数バックオフによるレート制限処理を実装済み
• ストリーミングのエラーを処理済み（エラーイベントリスナー）
• トークン使用量を監視済み（入力＋出力＋キャッシュ）
• サーバー側のみで使用（クライアント側から API を呼び出さない）
• 最新のモデル ID を使用済み（claude-sonnet-4-5-20250929）
• プロンプトキャッシュを設定済み（長いコンテキストを使用する場合）
• ツールスキーマを検証済み（関数呼び出しを使用する場合）
• 正しいモデル（3.7/4）で拡張思考を確認済み

---

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

1. よくある問題については references/top-errors.md を確認してください
2. セットアップ手順をすべて確認してください
3. 公式ドキュメントを確認してください：https://docs.claude.com/en/api
4. Console で API キーに正しい権限があることを確認してください

---

トークン効率：手動で API を統合する場合と比べて約 62% 削減（推定） エラー防止：100%（文書化された 12 件の問題をすべて防止） 開発時間：テンプレートを使えば 5 分、手動では 2 時間以上