claude-api

Claude API - 構造化出力とエラー防止ガイド

パッケージ：@anthropic-ai/[email protected]（2025年11月20日） 破壊的変更：2025年10月 - Claude 3.5／3.7 モデルが廃止、2025年11月 - 構造化出力のベータ版 最終更新日：2025-11-22

---

v0.69.0 以降の新機能（2025年11月）

主な機能：

1. 構造化出力（v0.69.0、2025年11月14日）- 重要 ⭐

JSON スキーマへの準拠を保証 - Claude の応答が、2 つのモードで指定した JSON スキーマに厳密に従います：

JSON 出力（output_format） - データ抽出とフォーマット用：

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: 'Extract contact info: John Doe, [email protected], 555-1234' }],
  betas: ['structured-outputs-2025-11-13'],
  output_format: {
    type: 'json_schema',
    json_schema: {
      name: 'Contact',
      strict: true,
      schema: {
        type: 'object',
        properties: {
          name: { type: 'string' },
          email: { type: 'string' },
          phone: { type: 'string' }
        },
        required: ['name', 'email', 'phone'],
        additionalProperties: false
      }
    }
  }
});

// Guaranteed valid JSON matching schema
const contact = JSON.parse(message.content[0].text);
console.log(contact.name); // "John Doe"

厳密なツール使用（strict: true） - 検証済みの関数パラメーター用：

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Get weather for San Francisco' }],
  betas: ['structured-outputs-2025-11-13'],
  tools: [{
    name: 'get_weather',
    description: 'Get current weather',
    input_schema: {
      type: 'object',
      properties: {
        location: { type: 'string' },
        unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
      },
      required: ['location'],
      additionalProperties: false
    },
    strict: true  // ← Guarantees schema compliance
  }]
});

要件：

• ベータヘッダー：structured-outputs-2025-11-13（betas 配列経由）
• モデル：Claude Sonnet 4.5、Claude Opus 4.1 のみ
• SDK：v0.69.0 以降が必要

制限事項：

• ❌ 再帰スキーマには対応していません
• ❌ 数値制約（minimum、maximum）には対応していません
• ❌ 正規表現のサポートは限定的です（後方参照／先読みには非対応）
• ❌ 引用およびメッセージのプレフィルとは併用できません
• ⚠️ 文法のコンパイルにより、初回リクエストのレイテンシーが増加します（24 時間キャッシュされます）

使用する場面：

• 非構造化テキストからのデータ抽出
• API レスポンスのフォーマット
• 検証済みのツール入力を必要とするエージェント型ワークフロー
• JSON パースエラーの解消

2. モデルの変更（2025年10月）- 破壊的変更

廃止（エラーが返されます）：

• ❌ Claude 3.5 Sonnet（すべてのバージョン）
• ❌ Claude 3.7 Sonnet - 非推奨（2025年10月28日）

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

モデル	ID	コンテキスト	最適な用途	コスト（100万トークンあたり）
Claude Sonnet 4.5	claude-sonnet-4-5-20250929	200k	バランスの取れた性能	$3/$15（入力／出力）
Claude Opus 4	claude-opus-4-20250514	200k	最高水準の性能	$15/$75
Claude Haiku 4.5	claude-3-5-haiku-20241022	200k	最先端に近い性能、高速	$1/$5

3. コンテキスト管理（2025年10月28日）

思考ブロックのクリア - 思考ブロックを自動的にクリーンアップします：

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 4096,
  messages: [{ role: 'user', content: 'Solve complex problem' }],
  betas: ['clear_thinking_20251015']
});
// Thinking blocks automatically managed

4. エージェントスキル API（2025年10月16日）

Office ファイル（PowerPoint、Excel、Word、PDF）向けの事前構築済みスキル：

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Analyze this spreadsheet' }],
  betas: ['skills-2025-10-02'],
  // Requires code execution tool enabled
});

📚 ドキュメント：https://platform.claude.com/docs/en/build-with-claude/structured-outputs

---

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

重要なエラーパターン - エラーは最初の 200 応答の後に発生します：

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

stream
  .on('error', (error) => {
    // Error can occur AFTER stream starts
    console.error('Stream error:', error);
    // Implement fallback or retry logic
  })
  .on('abort', (error) => {
    console.warn('Stream aborted:', error);
  });

重要な理由：通常の HTTP エラーとは異なり、SSE エラーは 200 OK の後、ストリームの途中で発生するため、エラーイベントリスナーが必要です。

---

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

重要なルール - cache_control は最後のブロックに指定する必要があります：

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  system: [
    {
      type: 'text',
      text: 'System instructions...',
    },
    {
      type: 'text',
      text: LARGE_CODEBASE, // 50k tokens
      cache_control: { type: 'ephemeral' }, // ← MUST be on LAST block
    },
  ],
  messages: [{ role: 'user', content: 'Explain auth module' }],
});

// Monitor cache usage
console.log('Cache reads:', message.usage.cache_read_input_tokens);
console.log('Cache writes:', message.usage.cache_creation_input_tokens);

最小要件：

• Claude Sonnet 4.5：最小 1,024 トークン
• Claude Haiku 4.5：最小 2,048 トークン
• TTL は 5 分（使用のたびに更新されます）
• キャッシュは内容が完全に一致する場合にのみ共有されます

---

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

重要なパターン：

厳密なツール使用（構造化出力を使用）：

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  betas: ['structured-outputs-2025-11-13'],
  tools: [{
    name: 'get_weather',
    description: 'Get weather data',
    input_schema: {
      type: 'object',
      properties: {
        location: { type: 'string' },
        unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
      },
      required: ['location'],
      additionalProperties: false
    },
    strict: true  // ← Guarantees schema compliance
  }],
  messages: [{ role: 'user', content: 'Weather in NYC?' }]
});

ツール結果のパターン - tool_use_id を一致させる必要があります：

const toolResults = [];
for (const block of response.content) {
  if (block.type === 'tool_use') {
    const result = await executeToolFunction(block.name, block.input);

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

messages.push({
  role: 'user',
  content: toolResults,
});

エラー処理 - ツールの実行失敗に対処します：

try {
  const result = await executeToolFunction(block.name, block.input);
  toolResults.push({
    type: 'tool_result',
    tool_use_id: block.id,
    content: JSON.stringify(result),
  });
} catch (error) {
  // Return error to Claude for handling
  toolResults.push({
    type: 'tool_result',
    tool_use_id: block.id,
    is_error: true,
    content: `Tool execution failed: ${error.message}`,
  });
}

---

ビジョン（画像理解）

重要なルール：

• 形式：JPEG、PNG、WebP、GIF（アニメーションなし）
• 最大サイズ：画像 1 枚あたり 5MB
• Base64 のオーバーヘッド：サイズが約 33% 増加します
• コンテキストへの影響：画像はトークン上限に含まれます
• キャッシュ：画像を繰り返し分析する場合はキャッシュを検討してください

形式の検証 - エンコード前に確認します：

const validFormats = ['image/jpeg', 'image/png', 'image/webp', 'image/gif'];
if (!validFormats.includes(mimeType)) {
  throw new Error(`Unsupported format: ${mimeType}`);
}

---

拡張思考モード

⚠️ モデルの互換性：

• ❌ Claude 3.7 Sonnet - 非推奨（2025年10月28日）
• ❌ Claude 3.5 Sonnet - 廃止（サポート対象外）
• ✅ Claude Sonnet 4.5 - 拡張思考に対応
• ✅ Claude Opus 4 - 拡張思考に対応

重要：

• 思考ブロックはキャッシュできません
• より大きい max_tokens が必要です（思考がトークンを消費します）
• 思考ブロックを想定する前にモデルを確認してください

---

レート制限

重大なパターン - 指数バックオフを用い、retry-after ヘッダーを尊重してください。

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) {
        // CRITICAL: Use retry-after header if present
        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');
}

レート制限ヘッダー：

• anthropic-ratelimit-requests-limit - 許可される合計 RPM
• anthropic-ratelimit-requests-remaining - 残りのリクエスト数
• anthropic-ratelimit-requests-reset - リセット時刻

---

エラー処理

一般的なエラーコード：

ステータス	エラータイプ	原因	解決策
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	システムが過負荷状態です	後でもう一度お試しください

重要：

• ストリーミングエラーは、最初の 200 レスポンスの後に発生します
• ストリームには必ずエラーイベントリスナーを実装してください
• 429 エラーでは retry-after ヘッダーを尊重してください
• 重要な操作にはフォールバック戦略を用意してください

---

既知の問題の防止

このスキルは、文書化されている 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://platform.claude.com/docs/en/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 の動作 発生する理由：システムプロンプトが messages 配列の後に配置されているため 防止策：システムプロンプトは必ず messages の前に配置します

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

エラー：invalid_request_error: messages: too many tokens 出典：モデルの制限 発生する理由：会話が長くなっても履歴を整理していないため 防止策：メッセージ履歴を整理する処理を実装し、キャッシュを使用します

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

エラー：レスポンスに思考ブロックがない 出典：モデルの機能 発生する理由：廃止済みまたは非推奨のモデル（3.5/3.7 Sonnet）を使用しているため 防止策：拡張思考には Claude Sonnet 4.5 または Claude Opus 4 のみを使用します

Issue #10: クライアントコードでの API キーの露出

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

Issue #11: レート制限のティアに関する混乱

エラー：想定より低い制限 原因：アカウントのティア制度 発生する理由：ティアの段階的な移行を理解していない 防止策：Console で現在のティアを確認する。使用状況に応じて自動的にスケールします

Issue #12: Message Batches のベータヘッダーが不足

エラー：invalid_request_error: unknown parameter: batches 原因：ベータ API の要件 発生する理由：anthropic-beta ヘッダーが不足している 防止策：anthropic-beta: message-batches-2024-09-24 ヘッダーを含める

---

公式ドキュメント

• Claude API: https://platform.claude.com/docs/en/api
• Messages API: https://platform.claude.com/docs/en/api/messages
• Structured Outputs: https://platform.claude.com/docs/en/build-with-claude/structured-outputs
• Prompt Caching: https://platform.claude.com/docs/en/build-with-claude/prompt-caching
• Tool Use: https://platform.claude.com/docs/en/build-with-claude/tool-use
• Vision: https://platform.claude.com/docs/en/build-with-claude/vision
• Rate Limits: https://platform.claude.com/docs/en/api/rate-limits
• Errors: https://platform.claude.com/docs/en/api/errors
• TypeScript SDK: https://github.com/anthropics/anthropic-sdk-typescript
• Context7 Library ID: /anthropics/anthropic-sdk-typescript

---

パッケージのバージョン

最新: @anthropic-ai/[email protected] (Nov 20, 2025)

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

---

トークン効率：

• スキルなし：~8,000 トークン（基本設定、ストリーミング、キャッシュ、ツール、ビジョン、エラー）
• スキルあり：~4,200 トークン（知識の不足部分、エラー防止、重要なパターン）
• 削減量：~48%（~3,800 トークン）

防止できるエラー：解決策を明記した 12 件の問題 主な価値：構造化出力（v0.69.0+）、モデルの非推奨化（Oct 2025）、プロンプトキャッシュのエッジケース、ストリーミングのエラーパターン、レート制限の再試行ロジック

---

最終確認日：2025-11-22 | スキルのバージョン：2.0.0 | 変更点：構造化出力（v0.69.0）を追加、モデル表を更新（3.5/3.7 を廃止）、コンテキスト管理とエージェントスキル API を追加。基本チュートリアル（約 380 行）を削除。知識の不足部分、エラー防止、高度なパターンに重点を置いています。